capistrano 3.0.0.pre2 → 3.0.0.pre3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 38d0a3ff8b874c2e4d430c269c18f76d93964753
-  data.tar.gz: 52b27720df0d2b9ae3908dcdaef8e1f5eca195af
+  metadata.gz: ec0cef7495327f81efcf4e79622e2e27af857334
+  data.tar.gz: 4657cf63f889a01ea11a16f4fb28208297d2ece3
 SHA512:
-  metadata.gz: 0dd61efc447d0b8169d354a126bbfb81845d739426e8c3d60752f3038f4e2c2b0f4fc9b94b87a7df41511ea49859193e04a525ef7fcd2ceb5b8d2bf6c7318b96
-  data.tar.gz: cf0d253ec7463e3e6e3f106d2f7ceaf30996b61156a59e42852de237f2556b786cc00b1781f016d734b77a995a848677a85023f04b1e687ebd5b6e3fbf8adc55
+  metadata.gz: d136e348c49b419e709851111825f264a6d8d94ba8038b8ca13d1fd21ffbe8308acdc49a83db1700700bc1f6f0beb64fad9a3c248bb2c17980a803e5a3dfe619
+  data.tar.gz: 81a2f3f73e250668a807a8f2abfd248dba05247e4c5cab8b73fd971a5691e842193800f7a58f63c43e661d76d74e0a039c19524fcf22a4f6992293d895667cf2

data/.gitignore

@@ -17,3 +17,4 @@ test/version_tmp
 tmp
 .rspec-local
 .ruby-version
+_site

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - 1.9.2
+  - rbx-19mode

data/README.md

@@ -1,5 +1,9 @@
 # Capistrano [![Build Status](https://travis-ci.org/capistrano/capistrano.png?branch=v3)](https://travis-ci.org/capistrano/capistrano)
 
+## Requirements
+
+* Ruby >= 1.9 (JRuby and C-Ruby/MRI are supported)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -55,7 +59,16 @@ $ cap production deploy --trace
 
 ## Tasks
 
-
+``` ruby
+server 'example.com', roles: [:web, :app]
+server 'example.org', roles: [:db, :workers]
+desc "Report Uptimes"
+task :uptime do
+  on roles(:all) do |host|
+    info "Host #{host} (#{host.roles.join(', ')}):\t#{capture(:uptime)}"
+  end
+end
+```
 
 ## Before / After
 
@@ -78,17 +91,108 @@ after :finishing, :notify do
 end
 ```
 
+If it makes sense for your use-case (often, that means *generating a file*)
+the Rake prerequisite mechanism can be used:
+
+``` ruby
+desc "Create Important File"
+file 'important.txt' do |t|
+  sh "touch #{t.name}"
+end
+desc "Upload Important File"
+task :upload => 'important.txt' do |t|
+  on roles(:all) do
+    upload!(t.prerequisites.first, '/tmp')
+  end
+end
+```
+
+The final way to call out to other tasks is to simply `invoke()` them:
+
+``` ruby
+task :one do
+  on roles(:all) { info "One" }
+end
+task :two do
+  invoke :one
+  on roles(:all) { info "Two" }
+end
+```
+
+This method is widely used.
+
+## Getting User Input
+
+``` ruby
+desc "Ask about breakfast"
+task :breakfast do
+  breakfast = ask(:breakfast, "What would you like your colleagues to you for breakfast?")
+  on roles(:all) do |h|
+    execute "echo \"$(whoami) wants #{breakfast} for breakfast!\" | wall"
+  end
+end
+```
+
+Perfect, who needs telephones.
+
 ## Console
 
-Execute arbitrary remote commands, to use this simply add 
-`require 'capistrano/console'` which will add the necessary tasks to your 
+**Note:** Here be dragons. The console is very immature, but it's much more
+cleanly architected than previous incarnations and it'll only get better from
+here on in.
+
+Execute arbitrary remote commands, to use this simply add
+`require 'capistrano/console'` which will add the necessary tasks to your
 environment:
 
 ``` shell
 $ cap staging console
 ```
 
+Then, after setting up the server connections, this is how that might look:
+
+```
+$ cap production console
+capistrano console - enter command to execute on production
+production> uptime
+ INFO [94db8027] Running /usr/bin/env uptime on leehambley@example.com:22
+DEBUG [94db8027] Command: /usr/bin/env uptime
+DEBUG [94db8027]   17:11:17 up 50 days, 22:31,  1 user,  load average: 0.02, 0.02, 0.05
+ INFO [94db8027] Finished in 0.435 seconds command successful.
+production> who
+ INFO [9ce34809] Running /usr/bin/env who on leehambley@example.com:22
+DEBUG [9ce34809] Command: /usr/bin/env who
+DEBUG [9ce34809]  leehambley pts/0        2013-06-13 17:11 (port-11262.pppoe.wtnet.de)
+ INFO [9ce34809] Finished in 0.420 seconds command successful.
+```
+
+## A word about PTYs
+
+There is a configuration option which asks the backend driver to as the remote host
+to assign the connection a *pty*. A *pty* is a pseudo-terminal, which in effect means
+*tell the backend that this is an **interactive** session*. This is normally a bad idea.
+
+Most of the differences are best explained by [this page](https://github.com/sstephenson/rbenv/wiki/Unix-shell-initialization) from the author of *rbenv*.
+
+**When Capistrano makes a connection it is a *non-login*, *non-interactive* shell.
+This was not an accident!**
+
+It's often used as a band aid to cure issues related to RVM and rbenv not loading login
+and shell initialisation scripts. In these scenarios RVM and rbenv are the tools at fault,
+or at least they are being used incorrectly.
+
+Whilst, especially in the case of language runtimes (Ruby, Node, Python and friends in
+particular) there is a temptation to run multiple versions in parallel on a single server
+and to switch between them using environmental variables, this is an anti-pattern, and
+sympotamtic of bad design (i.e. you're testing a second version of Ruby in production because
+your company lacks the infrastructure to test this in a staging environment)
+
 ## Configuration
 
 
-## SSHKit
+## SSHKit
+
+[SSHKit][https://github.com/capistrano/sshkit] is the driver for SSH
+connections behind the scenes in Capistrano, depending how deep you dig, you
+might run into interfaces that come directly from SSHKit (the configuration is
+a good example).

data/lib/capistrano/application.rb

@@ -1,9 +1,9 @@
 module Capistrano
   class Application < Rake::Application
-    include Rake::DSL
 
     def initialize
       super
+      @name = "cap"
       @rakefiles = %w{capfile Capfile capfile.rb Capfile.rb} << capfile
     end
 
@@ -12,6 +12,11 @@ module Capistrano
       super
     end
 
+    def sort_options(options)
+      options.push(version)
+      super
+    end
+
     def load_rakefile
       @name = 'cap'
       super
@@ -23,6 +28,16 @@ module Capistrano
     def capfile
       File.expand_path(File.join(File.dirname(__FILE__),'..','Capfile'))
     end
+
+    def version
+      ['--version', '-V',
+       "Display the program version.",
+       lambda { |value|
+         puts "Capistrano Version: #{Capistrano::VERSION} (Rake Version: #{RAKEVERSION})"
+         exit
+       }
+      ]
+    end
   end
 
 end

data/lib/capistrano/configuration.rb

@@ -29,35 +29,30 @@ module Capistrano
       end
     end
 
-    def role(name, hosts)
-      servers.add_role(name, hosts)
+    def role(name, hosts, options={})
+      servers.add_role(name, hosts, options)
     end
 
-    def server(name, properties = {})
+    def server(name, properties={})
       servers.add_host(name, properties)
     end
 
-    def roles_for(names, options = {})
-      servers.fetch_roles(names).tap do |list|
-        if filter = options.delete(:filter) || options.delete(:select)
-          if filter.respond_to?(:call)
-            list.select!(&filter)
-          else
-            list.select! { |s| s.properties.send(filter) }
-          end
-          if list.empty?
-            raise "Your filter #{filter} would remove all matching servers!"
-          end
-        end
-      end
+    def roles_for(names)
+      servers.roles_for(names)
     end
 
     def primary(role)
       servers.fetch_primary(role)
     end
 
+    def backend
+      @backend ||= SSHKit
+    end
+
+    attr_writer :backend
+
     def configure_backend
-      SSHKit.configure do |sshkit|
+      backend.configure do |sshkit|
         sshkit.format           = fetch(:format)
         sshkit.output_verbosity = fetch(:log_level)
         sshkit.default_env      = fetch(:default_env)

data/lib/capistrano/configuration/server.rb

@@ -2,9 +2,16 @@ require 'set'
 module Capistrano
   class Configuration
     class Server < SSHKit::Host
+      extend Forwardable
+      def_delegators :properties, :roles, :fetch, :set
+
+      def add_roles(roles)
+        Array(roles).each { |role| add_role(role) }
+      end
+      alias roles= add_roles
 
       def add_role(role)
-        roles << role.to_sym
+        roles.add role.to_sym
       end
 
       def has_role?(role)
@@ -15,8 +22,66 @@ module Capistrano
         hostname == Server.new(host).hostname
       end
 
-      def roles
-        properties.roles ||= Set.new
+      def primary
+        self if fetch(:primary)
+      end
+
+      def with(properties)
+        properties.each { |key, value| add_property(key, value) }
+        self
+      end
+
+      def properties
+        @properties ||= Properties.new
+      end
+
+      class Properties
+
+        def initialize
+          @properties = {}
+        end
+
+        def set(key, value)
+          @properties[key] = value
+        end
+
+        def fetch(key)
+          @properties[key]
+        end
+
+        def respond_to?(method)
+          @properties.has_key?(method)
+        end
+
+        def roles
+          @roles ||= Set.new
+        end
+
+        def method_missing(key, value=nil)
+          if value
+            set(lvalue(key), value)
+          else
+            fetch(key)
+          end
+        end
+
+        private
+
+        def lvalue(key)
+          key.to_s.chomp('=').to_sym
+        end
+
+      end
+
+
+      private
+
+      def add_property(key, value)
+        if respond_to?("#{key}=")
+          send("#{key}=", value)
+        else
+          set(key, value)
+        end
       end
 
     end

data/lib/capistrano/configuration/servers.rb

@@ -4,34 +4,22 @@ module Capistrano
     class Servers
       include Enumerable
 
-      def add_host(host, properties = {})
-        find_or_create_server(host).tap do |host|
-          Array(properties.delete(:roles) || properties.delete("roles")).each do |role|
-            host.add_role(role)
-          end
-          properties.each do |key, value|
-            unless host.properties.respond_to?(key)
-              host.properties.send(:"#{key}=", value)
-            end
-          end
-          servers.add host
-        end
+      def add_host(host, properties={})
+        servers.add server(host).with(properties)
       end
 
-      def add_role(role, hosts)
-        Array(hosts).each do |host|
-          server = find_or_create_server(host)
-          server.add_role(role)
-          servers.add server
-        end
+      def add_role(role, hosts, options={})
+        Array(hosts).each { |host| add_host(host, options.merge(roles: role)) }
       end
 
-      def fetch_roles(names)
-        roles_for(names)
+      def roles_for(names)
+        options = extract_options(names)
+        fetch_roles(names, options)
       end
 
       def fetch_primary(role)
-        fetch(role).select { |h| h.properties.primary }.first || fetch(role).first
+        hosts = fetch(role)
+        hosts.find(&:primary) || hosts.first
       end
 
       def each
@@ -40,25 +28,80 @@ module Capistrano
 
       private
 
-      def find_or_create_server(host)
-        servers.find { |server| server.matches?(host) } || Server.new(host)
+      def server(host)
+        if host.is_a? Server
+          host
+        else
+          servers.find { |server| server.matches?(host) } || Server.new(host)
+        end
       end
 
-      def fetch(name)
-        servers.find_all { |server| server.has_role? name }
+      def fetch(role)
+        servers.find_all { |server| server.has_role? role}
       end
 
-      def roles_for(names)
+      def fetch_roles(names, options)
         if Array(names).map(&:to_sym).include?(:all)
-          servers
+          filter(servers, options)
         else
-          Array(names).flat_map { |name| fetch name }.uniq
+          role_servers = Array(names).flat_map { |name| fetch name }.uniq
+          filter(role_servers, options)
         end
       end
 
+      def filter(servers, options)
+        Filter.new(servers, options).filtered_servers
+      end
+
       def servers
         @servers ||= Set.new
       end
+
+      def extract_options(array)
+        array.last.is_a?(::Hash) ? array.pop : {}
+      end
+
+      class Filter
+        def initialize(servers, options)
+          @servers, @options = servers, options
+        end
+
+        def filtered_servers
+          if servers_with_filter.any?
+            servers_with_filter
+          else
+            fail I18n.t(:filter_removes_all_servers, scope: :capistrano, filter: key )
+          end
+        end
+
+        private
+        attr_reader :options, :servers
+
+        def servers_with_filter
+          @servers_with_filter ||= servers.select(&filter)
+        end
+
+        def key
+          options[:filter] || options[:select]
+        end
+
+        def filter_option
+          key || all
+        end
+
+        def filter
+          if filter_option.respond_to?(:call)
+            filter_option
+          else
+            lambda { |server| server.fetch(filter_option) }
+          end
+        end
+
+        def all
+          lambda { |server| :all }
+        end
+
+      end
     end
   end
 end