capistrano 3.3.5 → 3.16.0

data/lib/capistrano/tasks/doctor.rake

@@ -0,0 +1,24 @@
+desc "Display a Capistrano troubleshooting report (all doctor: tasks)"
+task doctor: ["doctor:environment", "doctor:gems", "doctor:variables", "doctor:servers"]
+
+namespace :doctor do
+  desc "Display Ruby environment details"
+  task :environment do
+    Capistrano::Doctor::EnvironmentDoctor.new.call
+  end
+
+  desc "Display Capistrano gem versions"
+  task :gems do
+    Capistrano::Doctor::GemsDoctor.new.call
+  end
+
+  desc "Display the values of all Capistrano variables"
+  task :variables do
+    Capistrano::Doctor::VariablesDoctor.new.call
+  end
+
+  desc "Display the effective servers configuration"
+  task :servers do
+    Capistrano::Doctor::ServersDoctor.new.call
+  end
+end

data/lib/capistrano/tasks/framework.rake

@@ -1,50 +1,49 @@
 namespace :deploy do
-
-  desc 'Start a deployment, make sure server(s) ready.'
+  desc "Start a deployment, make sure server(s) ready."
   task :starting do
   end
 
-  desc 'Started'
+  desc "Started"
   task :started do
   end
 
-  desc 'Update server(s) by setting up a new release.'
+  desc "Update server(s) by setting up a new release."
   task :updating do
   end
 
-  desc 'Updated'
+  desc "Updated"
   task :updated do
   end
 
-  desc 'Revert server(s) to previous release.'
+  desc "Revert server(s) to previous release."
   task :reverting do
   end
 
-  desc 'Reverted'
+  desc "Reverted"
   task :reverted do
   end
 
-  desc 'Publish the release.'
+  desc "Publish the release."
   task :publishing do
   end
 
-  desc 'Published'
+  desc "Published"
   task :published do
   end
 
-  desc 'Finish the deployment, clean up server(s).'
+  desc "Finish the deployment, clean up server(s)."
   task :finishing do
   end
 
-  desc 'Finish the rollback, clean up server(s).'
+  desc "Finish the rollback, clean up server(s)."
   task :finishing_rollback do
   end
 
-  desc 'Finished'
+  desc "Finished"
   task :finished do
   end
 
-  desc 'Rollback to previous release.'
+  desc "Rollback to previous release."
   task :rollback do
     %w{ starting started
         reverting reverted
@@ -55,7 +54,7 @@ namespace :deploy do
   end
 end
 
-desc 'Deploy a new release.'
+desc "Deploy a new release."
 task :deploy do
   set(:deploying, true)
   %w{ starting started

data/lib/capistrano/tasks/install.rake

@@ -1,12 +1,12 @@
-require 'erb'
-require 'pathname'
-desc 'Install Capistrano, cap install STAGES=staging,production'
+require "erb"
+require "pathname"
+desc "Install Capistrano, cap install STAGES=staging,production"
 task :install do
-  envs = ENV['STAGES'] || 'staging,production'
+  envs = ENV["STAGES"] || "staging,production"
 
-  tasks_dir = Pathname.new('lib/capistrano/tasks')
-  config_dir = Pathname.new('config')
-  deploy_dir = config_dir.join('deploy')
+  tasks_dir = Pathname.new("lib/capistrano/tasks")
+  config_dir = Pathname.new("config")
+  deploy_dir = config_dir.join("deploy")
 
   deploy_rb = File.expand_path("../../templates/deploy.rb.erb", __FILE__)
   stage_rb = File.expand_path("../../templates/stage.rb.erb", __FILE__)
@@ -14,14 +14,14 @@ task :install do
 
   mkdir_p deploy_dir
 
-  entries = [{template: deploy_rb, file: config_dir.join('deploy.rb')}]
-  entries += envs.split(',').map { |stage| {template: stage_rb, file: deploy_dir.join("#{stage}.rb")} }
+  entries = [{ template: deploy_rb, file: config_dir.join("deploy.rb") }]
+  entries += envs.split(",").map { |stage| { template: stage_rb, file: deploy_dir.join("#{stage}.rb") } }
 
   entries.each do |entry|
-    if File.exists?(entry[:file])
+    if File.exist?(entry[:file])
       warn "[skip] #{entry[:file]} already exists"
     else
-      File.open(entry[:file], 'w+') do |f|
+      File.open(entry[:file], "w+") do |f|
         f.write(ERB.new(File.read(entry[:template])).result(binding))
         puts I18n.t(:written_file, scope: :capistrano, file: entry[:file])
       end
@@ -30,13 +30,12 @@ task :install do
 
   mkdir_p tasks_dir
 
-  if File.exists?('Capfile')
+  if File.exist?("Capfile")
     warn "[skip] Capfile already exists"
   else
-    FileUtils.cp(capfile, 'Capfile')
-    puts I18n.t(:written_file, scope: :capistrano, file: 'Capfile')
+    FileUtils.cp(capfile, "Capfile")
+    puts I18n.t(:written_file, scope: :capistrano, file: "Capfile")
   end
 
-
   puts I18n.t :capified, scope: :capistrano
 end

data/lib/capistrano/templates/Capfile

@@ -1,8 +1,19 @@
 # Load DSL and set up stages
-require 'capistrano/setup'
+require "capistrano/setup"
 
 # Include default deployment tasks
-require 'capistrano/deploy'
+require "capistrano/deploy"
+
+# Load the SCM plugin appropriate to your project:
+#
+# require "capistrano/scm/hg"
+# install_plugin Capistrano::SCM::Hg
+# or
+# require "capistrano/scm/svn"
+# install_plugin Capistrano::SCM::Svn
+# or
+require "capistrano/scm/git"
+install_plugin Capistrano::SCM::Git
 
 # Include tasks from other gems included in your Gemfile
 #
@@ -15,13 +26,13 @@ require 'capistrano/deploy'
 #   https://github.com/capistrano/rails
 #   https://github.com/capistrano/passenger
 #
-# require 'capistrano/rvm'
-# require 'capistrano/rbenv'
-# require 'capistrano/chruby'
-# require 'capistrano/bundler'
-# require 'capistrano/rails/assets'
-# require 'capistrano/rails/migrations'
-# require 'capistrano/passenger'
+# require "capistrano/rvm"
+# require "capistrano/rbenv"
+# require "capistrano/chruby"
+# require "capistrano/bundler"
+# require "capistrano/rails/assets"
+# require "capistrano/rails/migrations"
+# require "capistrano/passenger"
 
-# Load custom tasks from `lib/capistrano/tasks' if you have any defined
-Dir.glob('lib/capistrano/tasks/*.rake').each { |r| import r }
+# Load custom tasks from `lib/capistrano/tasks` if you have any defined
+Dir.glob("lib/capistrano/tasks/*.rake").each { |r| import r }

data/lib/capistrano/templates/deploy.rb.erb

@@ -1,48 +1,39 @@
-# config valid only for current version of Capistrano
-lock '<%= Capistrano::VERSION %>'
+# config valid for current version and patch releases of Capistrano
+lock "~> <%= Capistrano::VERSION %>"
 
-set :application, 'my_app_name'
-set :repo_url, 'git@example.com:me/my_repo.git'
+set :application, "my_app_name"
+set :repo_url, "git@example.com:me/my_repo.git"
 
 # Default branch is :master
-# ask :branch, proc { `git rev-parse --abbrev-ref HEAD`.chomp }.call
+# ask :branch, `git rev-parse --abbrev-ref HEAD`.chomp
 
 # Default deploy_to directory is /var/www/my_app_name
-# set :deploy_to, '/var/www/my_app_name'
+# set :deploy_to, "/var/www/my_app_name"
 
-# Default value for :scm is :git
-# set :scm, :git
+# Default value for :format is :airbrussh.
+# set :format, :airbrussh
 
-# Default value for :format is :pretty
-# set :format, :pretty
-
-# Default value for :log_level is :debug
-# set :log_level, :debug
+# You can configure the Airbrussh format using :format_options.
+# These are the defaults.
+# set :format_options, command_output: true, log_file: "log/capistrano.log", color: :auto, truncate: :auto
 
 # Default value for :pty is false
 # set :pty, true
 
 # Default value for :linked_files is []
-# set :linked_files, fetch(:linked_files, []).push('config/database.yml')
+# append :linked_files, "config/database.yml"
 
 # Default value for linked_dirs is []
-# set :linked_dirs, fetch(:linked_dirs, []).push('bin', 'log', 'tmp/pids', 'tmp/cache', 'tmp/sockets', 'vendor/bundle', 'public/system')
+# append :linked_dirs, "log", "tmp/pids", "tmp/cache", "tmp/sockets", "public/system"
 
 # Default value for default_env is {}
 # set :default_env, { path: "/opt/ruby/bin:$PATH" }
 
+# Default value for local_user is ENV['USER']
+# set :local_user, -> { `git config user.name`.chomp }
+
 # Default value for keep_releases is 5
 # set :keep_releases, 5
 
-namespace :deploy do
-
-  after :restart, :clear_cache do
-    on roles(:web), in: :groups, limit: 3, wait: 10 do
-      # Here we can do anything such as:
-      # within release_path do
-      #   execute :rake, 'cache:clear'
-      # end
-    end
-  end
-
-end
+# Uncomment the following to require manually verifying the host key before first deploy.
+# set :ssh_options, verify_host_key: :secure

data/lib/capistrano/templates/stage.rb.erb

@@ -1,45 +1,61 @@
-# Simple Role Syntax
+# server-based syntax
+# ======================
+# Defines a single server with a list of roles and multiple properties.
+# You can define all roles on a single server, or split them:
+
+# server "example.com", user: "deploy", roles: %w{app db web}, my_property: :my_value
+# server "example.com", user: "deploy", roles: %w{app web}, other_property: :other_value
+# server "db.example.com", user: "deploy", roles: %w{db}
+
+
+
+# role-based syntax
 # ==================
-# Supports bulk-adding hosts to roles, the primary server in each group
-# is considered to be the first unless any hosts have the primary
-# property set.  Don't declare `role :all`, it's a meta role.
 
-role :app, %w{deploy@example.com}
-role :web, %w{deploy@example.com}
-role :db,  %w{deploy@example.com}
+# Defines a role with one or multiple servers. The primary server in each
+# group is considered to be the first unless any hosts have the primary
+# property set. Specify the username and a domain or IP for the server.
+# Don't use `:all`, it's a meta role.
 
+# role :app, %w{deploy@example.com}, my_property: :my_value
+# role :web, %w{user1@primary.com user2@additional.com}, other_property: :other_value
+# role :db,  %w{deploy@example.com}
 
-# Extended Server Syntax
-# ======================
-# This can be used to drop a more detailed server definition into the
-# server list. The second argument is a, or duck-types, Hash and is
-# used to set extended properties on the server.
 
-server 'example.com', user: 'deploy', roles: %w{web app}, my_property: :my_value
+
+# Configuration
+# =============
+# You can set any configuration variable like in config/deploy.rb
+# These variables are then only loaded and set in this stage.
+# For available Capistrano configuration variables see the documentation page.
+# http://capistranorb.com/documentation/getting-started/configuration/
+# Feel free to add new variables to customise your setup.
+
 
 
 # Custom SSH Options
 # ==================
 # You may pass any option but keep in mind that net/ssh understands a
-# limited set of options, consult[net/ssh documentation](http://net-ssh.github.io/net-ssh/classes/Net/SSH.html#method-c-start).
+# limited set of options, consult the Net::SSH documentation.
+# http://net-ssh.github.io/net-ssh/classes/Net/SSH.html#method-c-start
 #
 # Global options
 # --------------
 #  set :ssh_options, {
-#    keys: %w(/home/rlisowski/.ssh/id_rsa),
+#    keys: %w(/home/user_name/.ssh/id_rsa),
 #    forward_agent: false,
 #    auth_methods: %w(password)
 #  }
 #
-# And/or per server (overrides global)
+# The server-based syntax can be used to override options:
 # ------------------------------------
-# server 'example.com',
-#   user: 'user_name',
+# server "example.com",
+#   user: "user_name",
 #   roles: %w{web app},
 #   ssh_options: {
-#     user: 'user_name', # overrides user setting above
+#     user: "user_name", # overrides user setting above
 #     keys: %w(/home/user_name/.ssh/id_rsa),
 #     forward_agent: false,
 #     auth_methods: %w(publickey password)
-#     # password: 'please use keys'
+#     # password: "please use keys"
 #   }

data/lib/capistrano/upload_task.rb

@@ -1,4 +1,4 @@
-require 'rake/file_creation_task'
+require "rake/file_creation_task"
 
 module Capistrano
   class UploadTask < Rake::FileCreationTask

data/lib/capistrano/version.rb

@@ -1,3 +1,3 @@
 module Capistrano
-  VERSION = "3.3.5"
+  VERSION = "3.16.0".freeze
 end

data/lib/capistrano/version_validator.rb

@@ -1,21 +1,17 @@
 module Capistrano
   class VersionValidator
-
     def initialize(version)
       @version = version
     end
 
     def verify
-      if match?
-        self
-      else
-        fail "Capfile locked at #{version}, but #{current_version} is loaded"
-      end
+      return self if match?
+      raise "Capfile locked at #{version}, but #{current_version} is loaded"
     end
 
     private
-    attr_reader :version
 
+    attr_reader :version
 
     def match?
       available =~ requested
@@ -26,12 +22,11 @@ module Capistrano
     end
 
     def available
-      Gem::Dependency.new('cap', version)
+      Gem::Dependency.new("cap", version)
     end
 
     def requested
-      Gem::Dependency.new('cap', current_version)
+      Gem::Dependency.new("cap", current_version)
     end
-
   end
 end

data/spec/integration/dsl_spec.rb

@@ -1,148 +1,177 @@
-require 'spec_helper'
+require "spec_helper"
 
 describe Capistrano::DSL do
-
   let(:dsl) { Class.new.extend Capistrano::DSL }
 
   before do
     Capistrano::Configuration.reset!
   end
 
-  describe 'setting and fetching hosts' do
-    describe 'when defining a host using the `server` syntax' do
+  describe "setting and fetching hosts" do
+    describe "when defining a host using the `server` syntax" do
       before do
-        dsl.server 'example1.com', roles: %w{web}, active: true
-        dsl.server 'example2.com', roles: %w{web}
-        dsl.server 'example3.com', roles: %w{app web}, active: true
-        dsl.server 'example4.com', roles: %w{app}, primary: true
-        dsl.server 'example5.com', roles: %w{db}, no_release: true
+        dsl.server "example1.com", roles: %w{web}, active: true
+        dsl.server "example2.com", roles: %w{web}
+        dsl.server "example3.com", roles: %w{app web}, active: true
+        dsl.server "example4.com", roles: %w{app}, primary: true
+        dsl.server "example5.com", roles: %w{db}, no_release: true, active: true
       end
 
-      describe 'fetching all servers' do
+      describe "fetching all servers" do
         subject { dsl.roles(:all) }
 
-        it 'returns all servers' do
+        it "returns all servers" do
           expect(subject.map(&:hostname)).to eq %w{example1.com example2.com example3.com example4.com example5.com}
         end
       end
 
-      describe 'fetching all release servers' do
-
-        context 'with no additional options' do
+      describe "fetching all release servers" do
+        context "with no additional options" do
           subject { dsl.release_roles(:all) }
 
-          it 'returns all release servers' do
+          it "returns all release servers" do
             expect(subject.map(&:hostname)).to eq %w{example1.com example2.com example3.com example4.com}
           end
         end
 
-        context 'with property filter options' do
+        context "with property filter options" do
           subject { dsl.release_roles(:all, filter: :active) }
 
-          it 'returns all release servers that match the property filter' do
+          it "returns all release servers that match the property filter" do
             expect(subject.map(&:hostname)).to eq %w{example1.com example3.com}
           end
         end
       end
 
-      describe 'fetching servers by multiple roles' do
+      describe "fetching servers by multiple roles" do
         it "does not confuse the last role with options" do
           expect(dsl.roles(:app, :web).count).to eq 4
           expect(dsl.roles(:app, :web, filter: :active).count).to eq 2
         end
       end
 
-      describe 'fetching servers by role' do
+      describe "fetching servers by role" do
         subject { dsl.roles(:app) }
 
-        it 'returns the servers' do
+        it "returns the servers" do
           expect(subject.map(&:hostname)).to eq %w{example3.com example4.com}
         end
       end
 
-      describe 'fetching servers by an array of roles' do
+      describe "fetching servers by an array of roles" do
         subject { dsl.roles([:app]) }
 
-        it 'returns the servers' do
+        it "returns the servers" do
           expect(subject.map(&:hostname)).to eq %w{example3.com example4.com}
         end
       end
 
-      describe 'fetching filtered servers by role' do
+      describe "fetching filtered servers by role" do
         subject { dsl.roles(:app, filter: :active) }
 
-        it 'returns the servers' do
+        it "returns the servers" do
           expect(subject.map(&:hostname)).to eq %w{example3.com}
         end
       end
 
-      describe 'fetching selected servers by role' do
+      describe "fetching selected servers by role" do
         subject { dsl.roles(:app, select: :active) }
 
-        it 'returns the servers' do
+        it "returns the servers" do
           expect(subject.map(&:hostname)).to eq %w{example3.com}
         end
       end
 
-      describe 'fetching the primary server by role' do
-        context 'when inferring primary status based on order' do
+      describe "fetching the primary server by role" do
+        context "when inferring primary status based on order" do
           subject { dsl.primary(:web) }
-          it 'returns the servers' do
-            expect(subject.hostname).to eq 'example1.com'
+          it "returns the servers" do
+            expect(subject.hostname).to eq "example1.com"
           end
         end
 
-        context 'when the attribute `primary` is explicitly set' do
+        context "when the attribute `primary` is explicitly set" do
           subject { dsl.primary(:app) }
-          it 'returns the servers' do
-            expect(subject.hostname).to eq 'example4.com'
+          it "returns the servers" do
+            expect(subject.hostname).to eq "example4.com"
           end
         end
       end
 
-      describe 'setting an internal host filter' do
+      describe "setting an internal host filter" do
         subject { dsl.roles(:app) }
-        it 'is ignored' do
-          dsl.set :filter, { host: 'example3.com' }
-          expect(subject.map(&:hostname)).to eq(['example3.com', 'example4.com'])
+        it "is ignored" do
+          dsl.set :filter, host: "example3.com"
+          expect(subject.map(&:hostname)).to eq(["example3.com", "example4.com"])
         end
       end
 
-      describe 'setting an internal role filter' do
+      describe "setting an internal role filter" do
         subject { dsl.roles(:app) }
-        it 'ignores it' do
-          dsl.set :filter, { role: :web }
-          expect(subject.map(&:hostname)).to eq(['example3.com','example4.com'])
+        it "ignores it" do
+          dsl.set :filter, role: :web
+          expect(subject.map(&:hostname)).to eq(["example3.com", "example4.com"])
         end
       end
 
-      describe 'setting an internal host and role filter' do
+      describe "setting an internal host and role filter" do
         subject { dsl.roles(:app) }
-        it 'ignores it' do
-          dsl.set :filter, { role: :web, host: 'example1.com' }
-          expect(subject.map(&:hostname)).to eq(['example3.com','example4.com'])
+        it "ignores it" do
+          dsl.set :filter, role: :web, host: "example1.com"
+          expect(subject.map(&:hostname)).to eq(["example3.com", "example4.com"])
         end
       end
 
-      describe 'setting an internal regexp host filter' do
+      describe "setting an internal regexp host filter" do
         subject { dsl.roles(:all) }
-        it 'is ignored' do
-          dsl.set :filter, { host: /1/ }
+        it "is ignored" do
+          dsl.set :filter, host: /1/
           expect(subject.map(&:hostname)).to eq(%w{example1.com example2.com example3.com example4.com example5.com})
         end
       end
 
+      describe "setting an internal hosts filter" do
+        subject { dsl.roles(:app) }
+        it "is ignored" do
+          dsl.set :filter, hosts: "example3.com"
+          expect(subject.map(&:hostname)).to eq(["example3.com", "example4.com"])
+        end
+      end
+
+      describe "setting an internal roles filter" do
+        subject { dsl.roles(:app) }
+        it "ignores it" do
+          dsl.set :filter, roles: :web
+          expect(subject.map(&:hostname)).to eq(["example3.com", "example4.com"])
+        end
+      end
+
+      describe "setting an internal hosts and roles filter" do
+        subject { dsl.roles(:app) }
+        it "ignores it" do
+          dsl.set :filter, roles: :web, hosts: "example1.com"
+          expect(subject.map(&:hostname)).to eq(["example3.com", "example4.com"])
+        end
+      end
+
+      describe "setting an internal regexp hosts filter" do
+        subject { dsl.roles(:all) }
+        it "is ignored" do
+          dsl.set :filter, hosts: /1/
+          expect(subject.map(&:hostname)).to eq(%w{example1.com example2.com example3.com example4.com example5.com})
+        end
+      end
     end
 
-    describe 'when defining role with reserved name' do
-      it 'fails with ArgumentError' do
-        expect {
+    describe "when defining role with reserved name" do
+      it "fails with ArgumentError" do
+        expect do
           dsl.role :all, %w{example1.com}
-        }.to raise_error(ArgumentError, "all reserved name for role. Please choose another name")
+        end.to raise_error(ArgumentError, "all reserved name for role. Please choose another name")
       end
     end
 
-    describe 'when defining hosts using the `role` syntax' do
+    describe "when defining hosts using the `role` syntax" do
       before do
         dsl.role :web, %w{example1.com example2.com example3.com}
         dsl.role :web, %w{example1.com}, active: true
@@ -152,223 +181,239 @@ describe Capistrano::DSL do
         dsl.role :db, %w{example5.com}, no_release: true
       end
 
-      describe 'fetching all servers' do
+      describe "fetching all servers" do
         subject { dsl.roles(:all) }
 
-        it 'returns all servers' do
+        it "returns all servers" do
           expect(subject.map(&:hostname)).to eq %w{example1.com example2.com example3.com example4.com example5.com}
         end
       end
 
-      describe 'fetching all release servers' do
-
-        context 'with no additional options' do
+      describe "fetching all release servers" do
+        context "with no additional options" do
           subject { dsl.release_roles(:all) }
 
-          it 'returns all release servers' do
+          it "returns all release servers" do
             expect(subject.map(&:hostname)).to eq %w{example1.com example2.com example3.com example4.com}
           end
         end
 
-        context 'with filter options' do
+        context "with filter options" do
           subject { dsl.release_roles(:all, filter: :active) }
 
-          it 'returns all release servers that match the filter' do
+          it "returns all release servers that match the filter" do
             expect(subject.map(&:hostname)).to eq %w{example1.com example3.com}
           end
         end
       end
 
-
-      describe 'fetching servers by role' do
+      describe "fetching servers by role" do
         subject { dsl.roles(:app) }
 
-        it 'returns the servers' do
+        it "returns the servers" do
           expect(subject.map(&:hostname)).to eq %w{example3.com example4.com}
         end
       end
 
-      describe 'fetching servers by an array of roles' do
+      describe "fetching servers by an array of roles" do
         subject { dsl.roles([:app]) }
 
-        it 'returns the servers' do
+        it "returns the servers" do
           expect(subject.map(&:hostname)).to eq %w{example3.com example4.com}
         end
       end
 
-      describe 'fetching filtered servers by role' do
+      describe "fetching filtered servers by role" do
         subject { dsl.roles(:app, filter: :active) }
 
-        it 'returns the servers' do
+        it "returns the servers" do
           expect(subject.map(&:hostname)).to eq %w{example3.com}
         end
       end
 
-      describe 'fetching selected servers by role' do
+      describe "fetching selected servers by role" do
         subject { dsl.roles(:app, select: :active) }
 
-        it 'returns the servers' do
+        it "returns the servers" do
           expect(subject.map(&:hostname)).to eq %w{example3.com}
         end
       end
 
-      describe 'fetching the primary server by role' do
-        context 'when inferring primary status based on order' do
+      describe "fetching the primary server by role" do
+        context "when inferring primary status based on order" do
           subject { dsl.primary(:web) }
-          it 'returns the servers' do
-            expect(subject.hostname).to eq 'example1.com'
+          it "returns the servers" do
+            expect(subject.hostname).to eq "example1.com"
           end
         end
 
-        context 'when the attribute `primary` is explicity set' do
+        context "when the attribute `primary` is explicity set" do
           subject { dsl.primary(:app) }
-          it 'returns the servers' do
-            expect(subject.hostname).to eq 'example4.com'
+          it "returns the servers" do
+            expect(subject.hostname).to eq "example4.com"
           end
         end
       end
-
     end
 
-    describe 'when defining a host using a combination of the `server` and `role` syntax' do
-
+    describe "when defining a host using a combination of the `server` and `role` syntax" do
       before do
-        dsl.server 'db@example1.com:1234', roles: %w{db}, active: true
-        dsl.server 'root@example1.com:1234', roles: %w{web}, active: true
-        dsl.server 'example1.com:5678', roles: %w{web}, active: true
+        dsl.server "db@example1.com:1234", roles: %w{db}, active: true
+        dsl.server "root@example1.com:1234", roles: %w{web}, active: true
+        dsl.server "example1.com:5678", roles: %w{web}, active: true
         dsl.role :app, %w{deployer@example1.com:1234}
         dsl.role :app, %w{example1.com:5678}
       end
 
-      describe 'fetching all servers' do
-        subject { dsl.roles(:all).map { |server| "#{server.user}@#{server.hostname}:#{server.port}" } }
-
-        it 'creates a server instance for each unique user@host:port combination' do
-          expect(subject).to eq %w{db@example1.com:1234 root@example1.com:1234 @example1.com:5678 deployer@example1.com:1234}
+      describe "fetching all servers" do
+        it "creates one server per hostname, ignoring user combinations" do
+          expect(dsl.roles(:all).size).to eq(2)
         end
       end
 
-      describe 'fetching servers for a role' do
-        it 'roles defined using the `server` syntax are included' do
-          expect(dsl.roles(:web).size).to eq(2)
+      describe "fetching servers for a role" do
+        it "roles defined using the `server` syntax are included" do
+          as = dsl.roles(:web).map { |server| "#{server.user}@#{server.hostname}:#{server.port}" }
+          expect(as.size).to eq(2)
+          expect(as[0]).to eq("deployer@example1.com:1234")
+          expect(as[1]).to eq("@example1.com:5678")
         end
 
-        it 'roles defined using the `role` syntax are included' do
-          expect(dsl.roles(:app).size).to eq(2)
+        it "roles defined using the `role` syntax are included" do
+          as = dsl.roles(:app).map { |server| "#{server.user}@#{server.hostname}:#{server.port}" }
+          expect(as.size).to eq(2)
+          expect(as[0]).to eq("deployer@example1.com:1234")
+          expect(as[1]).to eq("@example1.com:5678")
         end
       end
-
     end
 
-  end
+    describe "when setting user and port" do
+      subject { dsl.roles(:all).map { |server| "#{server.user}@#{server.hostname}:#{server.port}" }.first }
+
+      describe "using the :user property" do
+        it "takes precedence over in the host string" do
+          dsl.server "db@example1.com:1234", roles: %w{db}, active: true, user: "brian"
+          expect(subject).to eq("brian@example1.com:1234")
+        end
+      end
 
-  describe 'setting and fetching variables' do
+      describe "using the :port property" do
+        it "takes precedence over in the host string" do
+          dsl.server "db@example1.com:9090", roles: %w{db}, active: true, port: 1234
+          expect(subject).to eq("db@example1.com:1234")
+        end
+      end
+    end
+  end
 
+  describe "setting and fetching variables" do
     before do
       dsl.set :scm, :git
     end
 
-    context 'without a default' do
-      context 'when the variables is defined' do
-        it 'returns the variable' do
+    context "without a default" do
+      context "when the variables is defined" do
+        it "returns the variable" do
           expect(dsl.fetch(:scm)).to eq :git
         end
       end
 
-      context 'when the variables is undefined' do
-        it 'returns nil' do
+      context "when the variables is undefined" do
+        it "returns nil" do
           expect(dsl.fetch(:source_control)).to be_nil
         end
       end
     end
 
-    context 'with a default' do
-      context 'when the variables is defined' do
-        it 'returns the variable' do
+    context "with a default" do
+      context "when the variables is defined" do
+        it "returns the variable" do
           expect(dsl.fetch(:scm, :svn)).to eq :git
         end
       end
 
-      context 'when the variables is undefined' do
-        it 'returns the default' do
+      context "when the variables is undefined" do
+        it "returns the default" do
           expect(dsl.fetch(:source_control, :svn)).to eq :svn
         end
       end
     end
 
-    context 'with a block' do
-      context 'when the variables is defined' do
-        it 'returns the variable' do
+    context "with a block" do
+      context "when the variables is defined" do
+        it "returns the variable" do
           expect(dsl.fetch(:scm) { :svn }).to eq :git
         end
       end
 
-      context 'when the variables is undefined' do
-        it 'calls the block' do
+      context "when the variables is undefined" do
+        it "calls the block" do
           expect(dsl.fetch(:source_control) { :svn }).to eq :svn
         end
       end
     end
-
   end
 
-  describe 'asking for a variable' do
+  describe "asking for a variable" do
+    let(:stdin) { stub(tty?: true) }
+
     before do
-      dsl.ask(:scm, :svn)
+      dsl.ask(:scm, :svn, stdin: stdin)
       $stdout.stubs(:print)
     end
 
-    context 'variable is provided' do
+    context "variable is provided" do
       before do
-        $stdin.expects(:gets).returns('git')
+        stdin.expects(:gets).returns("git")
       end
 
-      it 'sets the input as the variable' do
-        expect(dsl.fetch(:scm)).to eq 'git'
+      it "sets the input as the variable" do
+        expect(dsl.fetch(:scm)).to eq "git"
       end
     end
 
-    context 'variable is not provided' do
+    context "variable is not provided" do
       before do
-        $stdin.expects(:gets).returns('')
+        stdin.expects(:gets).returns("")
       end
 
-      it 'sets the variable as the default' do
+      it "sets the variable as the default" do
         expect(dsl.fetch(:scm)).to eq :svn
       end
     end
   end
 
-  describe 'checking for presence' do
+  describe "checking for presence" do
     subject { dsl.any? :linked_files }
 
     before do
       dsl.set(:linked_files, linked_files)
     end
 
-    context 'variable is an non-empty array' do
+    context "variable is an non-empty array" do
       let(:linked_files) { %w{1} }
 
       it { expect(subject).to be_truthy }
     end
 
-    context 'variable is an empty array' do
+    context "variable is an empty array" do
       let(:linked_files) { [] }
       it { expect(subject).to be_falsey }
     end
 
-    context 'variable exists, is not an array' do
+    context "variable exists, is not an array" do
       let(:linked_files) { stub }
       it { expect(subject).to be_truthy }
     end
 
-    context 'variable is nil' do
+    context "variable is nil" do
       let(:linked_files) { nil }
       it { expect(subject).to be_falsey }
     end
   end
 
-  describe 'configuration SSHKit' do
+  describe "configuration SSHKit" do
     let(:config) { SSHKit.config }
     let(:backend) { SSHKit.config.backend.config }
     let(:default_env) { { rails_env: :production } }
@@ -379,232 +424,209 @@ describe Capistrano::DSL do
       dsl.set(:default_env, default_env)
       dsl.set(:pty, true)
       dsl.set(:connection_timeout, 10)
-      dsl.set(:ssh_options, {
-        keys: %w(/home/user/.ssh/id_rsa),
-        forward_agent: false,
-        auth_methods: %w(publickey password)
-      })
+      dsl.set(:ssh_options, keys: %w(/home/user/.ssh/id_rsa),
+                            forward_agent: false,
+                            auth_methods: %w(publickey password))
       dsl.configure_backend
     end
 
-    it 'sets the output' do
+    it "sets the output" do
       expect(config.output).to be_a SSHKit::Formatter::Dot
     end
 
-    it 'sets the output verbosity' do
+    it "sets the output verbosity" do
       expect(config.output_verbosity).to eq 0
     end
 
-    it 'sets the default env' do
+    it "sets the default env" do
       expect(config.default_env).to eq default_env
     end
 
-    it 'sets the backend pty' do
+    it "sets the backend pty" do
       expect(backend.pty).to be_truthy
     end
 
-    it 'sets the backend connection timeout' do
+    it "sets the backend connection timeout" do
       expect(backend.connection_timeout).to eq 10
     end
 
-    it 'sets the backend ssh_options' do
+    it "sets the backend ssh_options" do
       expect(backend.ssh_options[:keys]).to eq %w(/home/user/.ssh/id_rsa)
       expect(backend.ssh_options[:forward_agent]).to eq false
       expect(backend.ssh_options[:auth_methods]).to eq %w(publickey password)
     end
-
   end
 
-  describe 'release path' do
-
-    before do
-      dsl.set(:deploy_to, '/var/www')
-    end
-
-    describe 'fetching release path' do
-      subject { dsl.release_path }
-
-      context 'where no release path has been set' do
-        before do
-          dsl.delete(:release_path)
-        end
-
-        it 'returns the `current_path` value' do
-          expect(subject.to_s).to eq '/var/www/current'
-        end
+  describe "on()" do
+    describe "when passed server objects" do
+      before do
+        dsl.server "example1.com", roles: %w{web}, active: true
+        dsl.server "example2.com", roles: %w{web}
+        dsl.server "example3.com", roles: %w{app web}, active: true
+        dsl.server "example4.com", roles: %w{app}, primary: true
+        dsl.server "example5.com", roles: %w{db}, no_release: true
+        @coordinator = mock("coordinator")
+        @coordinator.expects(:each).returns(nil)
+        ENV.delete "ROLES"
+        ENV.delete "HOSTS"
       end
 
-      context 'where the release path has been set' do
-        before do
-          dsl.set(:release_path, '/var/www/release_path')
-        end
-
-        it 'returns the set `release_path` value' do
-          expect(subject.to_s).to eq '/var/www/release_path'
-        end
+      it "filters by role from the :filter variable" do
+        hosts = dsl.roles(:web)
+        all = dsl.roles(:all)
+        SSHKit::Coordinator.expects(:new).with(hosts).returns(@coordinator)
+        dsl.set :filter, role: "web"
+        dsl.on(all)
       end
-    end
-
-    describe 'setting release path' do
-      let(:now) { Time.parse("Oct 21 16:29:00 2015") }
-      subject { dsl.release_path }
 
-      context 'without a timestamp' do
-        before do
-          dsl.env.expects(:timestamp).returns(now)
-          dsl.set_release_path
-        end
-
-        it 'returns the release path with the current env timestamp' do
-          expect(subject.to_s).to eq '/var/www/releases/20151021162900'
-        end
+      it "filters by host and role from the :filter variable" do
+        all = dsl.roles(:all)
+        SSHKit::Coordinator.expects(:new).with([]).returns(@coordinator)
+        dsl.set :filter, role: "db", host: "example3.com"
+        dsl.on(all)
       end
 
-      context 'with a timestamp' do
-        before do
-          dsl.set_release_path('timestamp')
-        end
-
-        it 'returns the release path with the timestamp' do
-          expect(subject.to_s).to eq '/var/www/releases/timestamp'
-        end
+      it "filters by roles from the :filter variable" do
+        hosts = dsl.roles(:web)
+        all = dsl.roles(:all)
+        SSHKit::Coordinator.expects(:new).with(hosts).returns(@coordinator)
+        dsl.set :filter, roles: "web"
+        dsl.on(all)
       end
-    end
-
-    describe 'setting deploy configuration path' do
-      subject { dsl.deploy_config_path.to_s }
 
-      context 'where no config path is set' do
-        before do
-          dsl.delete(:deploy_config_path)
-        end
+      it "filters by hosts and roles from the :filter variable" do
+        all = dsl.roles(:all)
+        SSHKit::Coordinator.expects(:new).with([]).returns(@coordinator)
+        dsl.set :filter, roles: "db", hosts: "example3.com"
+        dsl.on(all)
+      end
 
-        it 'returns "config/deploy.rb"' do
-          expect(subject).to eq 'config/deploy.rb'
-        end
+      it "filters from ENV[ROLES]" do
+        hosts = dsl.roles(:db)
+        all = dsl.roles(:all)
+        SSHKit::Coordinator.expects(:new).with(hosts).returns(@coordinator)
+        ENV["ROLES"] = "db"
+        dsl.on(all)
       end
 
-      context 'where a custom path is set' do
-        before do
-          dsl.set(:deploy_config_path, 'my/custom/path.rb')
-        end
+      it "filters from ENV[HOSTS]" do
+        hosts = dsl.roles(:db)
+        all = dsl.roles(:all)
+        SSHKit::Coordinator.expects(:new).with(hosts).returns(@coordinator)
+        ENV["HOSTS"] = "example5.com"
+        dsl.on(all)
+      end
 
-        it 'returns the custom path' do
-          expect(subject).to eq 'my/custom/path.rb'
-        end
+      it "filters by ENV[HOSTS] && ENV[ROLES]" do
+        all = dsl.roles(:all)
+        SSHKit::Coordinator.expects(:new).with([]).returns(@coordinator)
+        ENV["HOSTS"] = "example5.com"
+        ENV["ROLES"] = "web"
+        dsl.on(all)
       end
     end
 
-    describe 'setting stage configuration path' do
-      subject { dsl.stage_config_path.to_s }
-
-      context 'where no config path is set' do
-
-        before do
-          dsl.delete(:stage_config_path)
-        end
-
-        it 'returns "config/deploy"' do
-          expect(subject).to eq 'config/deploy'
-        end
+    describe "when passed server literal names" do
+      before do
+        ENV.delete "ROLES"
+        ENV.delete "HOSTS"
+        @coordinator = mock("coordinator")
+        @coordinator.expects(:each).returns(nil)
       end
 
-      context 'where a custom path is set' do
-        before do
-          dsl.set(:stage_config_path, 'my/custom/path')
-        end
-
-        it 'returns the custom path' do
-          expect(subject).to eq 'my/custom/path'
-        end
+      it "selects nothing when a role filter is present" do
+        dsl.set :filter, role: "web"
+        SSHKit::Coordinator.expects(:new).with([]).returns(@coordinator)
+        dsl.on("my.server")
       end
-    end
-  end
-
-  describe 'local_user' do
-    before do
-      dsl.set :local_user, -> { Etc.getlogin }
-    end
 
-    describe 'fetching local_user' do
-      subject { dsl.local_user }
+      it "selects using the string when a host filter is present" do
+        dsl.set :filter, host: "server.local"
+        SSHKit::Coordinator.expects(:new).with(["server.local"]).returns(@coordinator)
+        dsl.on("server.local")
+      end
 
-      context 'where a local_user is not set' do
-        before do
-          Etc.expects(:getlogin).returns('login')
-        end
+      it "doesn't select when a host filter is present that doesn't match" do
+        dsl.set :filter, host: "ruby.local"
+        SSHKit::Coordinator.expects(:new).with([]).returns(@coordinator)
+        dsl.on("server.local")
+      end
 
-        it 'returns the login name' do
-          expect(subject.to_s).to eq 'login'
-        end
+      it "selects nothing when a roles filter is present" do
+        dsl.set :filter, roles: "web"
+        SSHKit::Coordinator.expects(:new).with([]).returns(@coordinator)
+        dsl.on("my.server")
       end
 
-      context 'where a local_user is set' do
-        before do
-          dsl.set(:local_user, -> { 'custom login' })
-        end
+      it "selects using the string when a hosts filter is present" do
+        dsl.set :filter, hosts: "server.local"
+        SSHKit::Coordinator.expects(:new).with(["server.local"]).returns(@coordinator)
+        dsl.on("server.local")
+      end
 
-        it 'returns the custom name' do
-          expect(subject.to_s).to eq 'custom login'
-        end
+      it "doesn't select when a hosts filter is present that doesn't match" do
+        dsl.set :filter, hosts: "ruby.local"
+        SSHKit::Coordinator.expects(:new).with([]).returns(@coordinator)
+        dsl.on("server.local")
       end
     end
   end
 
-  describe 'on()' do
-
+  describe "role_properties()" do
     before do
-      dsl.server 'example1.com', roles: %w{web}, active: true
-      dsl.server 'example2.com', roles: %w{web}
-      dsl.server 'example3.com', roles: %w{app web}, active: true
-      dsl.server 'example4.com', roles: %w{app}, primary: true
-      dsl.server 'example5.com', roles: %w{db}, no_release: true
-      @coordinator = mock('coordinator')
-      @coordinator.expects(:each).returns(nil)
-      ENV.delete 'ROLES'
-      ENV.delete 'HOSTS'
-
+      dsl.role :redis, %w[example1.com example2.com], redis: { port: 6379, type: :slave }
+      dsl.server "example1.com", roles: %w{web}, active: true, web: { port: 80 }
+      dsl.server "example2.com", roles: %w{web redis}, web: { port: 81 }, redis: { type: :master }
+      dsl.server "example3.com", roles: %w{app}, primary: true
     end
 
-    it 'filters by role from the :filter variable' do
-      hosts = dsl.roles(:web)
-      all = dsl.roles(:all)
-      SSHKit::Coordinator.expects(:new).with(hosts).returns(@coordinator)
-      dsl.set :filter, { role: 'web' }
-      dsl.on(all)
+    it "retrieves properties for a single role as a set" do
+      rps = dsl.role_properties(:app)
+      expect(rps).to eq(Set[{ hostname: "example3.com", role: :app }])
     end
 
-    it 'filters by host and role from the :filter variable' do
-      all = dsl.roles(:all)
-      SSHKit::Coordinator.expects(:new).with([]).returns(@coordinator)
-      dsl.set :filter, { role: 'db', host: 'example3.com' }
-      dsl.on(all)
+    it "retrieves properties for multiple roles as a set" do
+      rps = dsl.role_properties(:app, :web)
+      expect(rps).to eq(Set[{ hostname: "example3.com", role: :app }, { hostname: "example1.com", role: :web, port: 80 }, { hostname: "example2.com", role: :web, port: 81 }])
     end
 
-    it 'filters from ENV[ROLES]' do
-      hosts = dsl.roles(:db)
-      all = dsl.roles(:all)
-      SSHKit::Coordinator.expects(:new).with(hosts).returns(@coordinator)
-      ENV['ROLES'] = 'db'
-      dsl.on(all)
+    it "yields the properties for a single role" do
+      recipient = mock("recipient")
+      recipient.expects(:doit).with("example1.com", :redis, port: 6379, type: :slave)
+      recipient.expects(:doit).with("example2.com", :redis, port: 6379, type: :master)
+      dsl.role_properties(:redis) do |host, role, props|
+        recipient.doit(host, role, props)
+      end
     end
 
-    it 'filters from ENV[HOSTS]' do
-      hosts = dsl.roles(:db)
-      all = dsl.roles(:all)
-      SSHKit::Coordinator.expects(:new).with(hosts).returns(@coordinator)
-      ENV['HOSTS'] = 'example5.com'
-      dsl.on(all)
+    it "yields the properties for multiple roles" do
+      recipient = mock("recipient")
+      recipient.expects(:doit).with("example1.com", :redis, port: 6379, type: :slave)
+      recipient.expects(:doit).with("example2.com", :redis, port: 6379, type: :master)
+      recipient.expects(:doit).with("example3.com", :app, nil)
+      dsl.role_properties(:redis, :app) do |host, role, props|
+        recipient.doit(host, role, props)
+      end
     end
 
-    it 'filters by ENV[HOSTS] && ENV[ROLES]' do
-      all = dsl.roles(:all)
-      SSHKit::Coordinator.expects(:new).with([]).returns(@coordinator)
-      ENV['HOSTS'] = 'example5.com'
-      ENV['ROLES'] = 'web'
-      dsl.on(all)
+    it "yields the merged properties for multiple roles" do
+      recipient = mock("recipient")
+      recipient.expects(:doit).with("example1.com", :redis, port: 6379, type: :slave)
+      recipient.expects(:doit).with("example2.com", :redis, port: 6379, type: :master)
+      recipient.expects(:doit).with("example1.com", :web, port: 80)
+      recipient.expects(:doit).with("example2.com", :web, port: 81)
+      dsl.role_properties(:redis, :web) do |host, role, props|
+        recipient.doit(host, role, props)
+      end
     end
 
+    it "honours a property filter before yielding" do
+      recipient = mock("recipient")
+      recipient.expects(:doit).with("example1.com", :redis, port: 6379, type: :slave)
+      recipient.expects(:doit).with("example1.com", :web, port: 80)
+      dsl.role_properties(:redis, :web, select: :active) do |host, role, props|
+        recipient.doit(host, role, props)
+      end
+    end
   end
-
 end