capistrano/capistrano — pull request #475 by skisulli (2013-05-18 21:13:00+00:00)
Title: Support loading multistage configs from any directory in the Capistrano load_paths

Support loading stage configs from additional directories

**This is an epic commit message. TL;DR**
Add a `file_in_load_path?` method to determine if a file is in the Capistrano load_paths, and change the multistage extension to use `file_in_load_path?` instead of `File.exists?` when loading stage configs.

I am working on a private Capistrano gem to consolidate our deploys into one project. We are deploying to EC2 and use tags on the instances to determine where to deploy each application to. Therefore the Capistrano configuration for all of our applications is almost identical with the only difference being the application name, and things that can be derived from the application name. I want to be able to use the Capistrano multistage extension to configure our different environments. While testing this I discovered that I can not load the stage configs from within my gem.

I tried the following config:

```ruby
set :stage_dir, 'stages/aws'
set :stages, %w(production staging)
set :default_stage, 'staging'
```

This config would not load the proper configs because stages/aws was not found by the `File.exists?` call on [multistage.rb#18](https://github.com/capistrano/capistrano/blob/master/lib/capistrano/ext/multistage.rb#L18)

Then I tried this config:

```ruby
set :stage_dir, File.join(File.dirname(__FILE__), 'stages', 'aws')
set :stages, %w(production staging)
set :default_stage, 'staging'
```

The multistage gem found the file in this example, but failed due to the path not being in the Capistrano load_path. I tried adding the `File.dirname(__FILE__)` to the load_path, but that did not work because I still had to set `:stage_dir` to `File.join(File.dirname(__FILE__), 'stages', 'aws')` in order for load to be called.

To fix this I added a method to loading.rb to scan the load_paths for the file requested, and updated the multistage extension to use the new method.