capistrano 2.2.0 → 2.3.0

data/CHANGELOG

@@ -1,3 +1,32 @@
+*2.3.0* May 2, 2008
+
+* Make sure git fetches include tags [Alex Arnell]
+
+* Make deploy:setup obey the :use_sudo and :runner directives, and generalize the :use_sudo and :runner options into a try_sudo() helper method [Jamis Buck]
+
+* Make sudo helper play nicely with complex command chains [Jamis Buck]
+
+* Expand file-transfer options with new upload() and download() helpers. [Jamis Buck]
+
+* Allow SCP transfers in addition to SFTP. [Jamis Buck]
+
+* Use Net::SSH v2 and Net::SSH::Gateway. [Jamis Buck]
+
+* Added #export method for git SCM [Phillip Goldenburg]
+
+* For query_revision, git SCM used git-rev-parse on the repo hosting the Capfile, which may NOT be the same tree as the actual source reposistory. Use git-ls-remote instead to resolve the revision for checkout. [Robin H. Johnson]
+
+* Allow :ssh_options hash to be specified per server [Jesse Newland]
+
+* Added support for depend :remote, :file to test for existence of a specific file [Andrew Carter]
+
+* Ensure that the default run options are mixed into the command options when executing a command from the cap shell [Ken Collins]
+
+* Added :none SCM module for deploying a specific directory's contents [Jamis Buck]
+
+* Improved "copy" strategy supports local caching and pattern exclusion (via :copy_cache and :copy_exclude variables) [Jamis Buck]
+
+
 *2.2.0* February 27, 2008
 
 * Fix git submodule support to init on sync [halorgium]

data/README

@@ -7,8 +7,10 @@ Capistrano was originally designed to simplify and automate deployment of web ap
 
 == Dependencies
 
-* Net::SSH and Net::SFTP (http://net-ssh.rubyforge.org)
-* Needle (via Net::SSH)
+* Net::SSH v2 (http://net-ssh.rubyforge.org)
+* Net::SFTP v2 (http://net-ssh.rubyforge.org)
+* Net::SCP v1 (http://net-ssh.rubyforge.org)
+* Net::SSH::Gateway v1 (http://net-ssh.rubyforge.org)
 * HighLine (http://highline.rubyforge.org)
 
 If you want to run the tests, you'll also need to have the following dependencies installed:
@@ -36,8 +38,3 @@ Use the +cap+ script as follows:
     cap sometask
 
 By default, the script will look for a file called one of +capfile+ or +Capfile+. The +someaction+ text indicates which task to execute. You can do "cap -h" to see all the available options and "cap -T" to see all the available tasks.
-
-== KNOWN ISSUES
-
-* Using "put" to upload a file to two or more hosts when a gateway is in effect has a good chance of crashing with a "corrupt mac detected" error. This is due to a bug in Net::SSH.
-* Running commands may rarely hang inexplicably. This appears to be specific only to certain platforms. Most people will never see this behavior.

data/lib/capistrano/command.rb

@@ -1,10 +1,13 @@
 require 'capistrano/errors'
+require 'capistrano/processable'
 
 module Capistrano
 
   # This class encapsulates a single command to be executed on a set of remote
   # machines, in parallel.
   class Command
+    include Processable
+
     attr_reader :command, :sessions, :options
 
     def self.process(command, sessions, options={}, &block)
@@ -32,21 +35,8 @@ module Capistrano
     # fails (non-zero return code) on any of the hosts, this will raise a
     # Capistrano::CommandError.
     def process!
-      since = Time.now
       loop do
-        active = 0
-        @channels.each do |ch|
-          next if ch[:closed]
-          active += 1
-          ch.connection.process(true)
-        end
-
-        break if active == 0
-        if Time.now - since >= 1
-          since = Time.now
-          @channels.each { |ch| ch.connection.ping! }
-        end
-        sleep 0.01 # a brief respite, to keep the CPU from going crazy
+        break unless process_iteration { @channels.any? { |ch| !ch[:closed] } }
       end
 
       logger.trace "command finished" if logger
@@ -84,38 +74,32 @@ module Capistrano
             channel[:host] = server.host
             channel[:options] = options
 
-            execute_command = Proc.new do |ch|
-              logger.trace "executing command", ch[:server] if logger
-              cmd = replace_placeholders(command, ch)
-
-              if options[:shell] == false
-                shell = nil
-              else
-                shell = "#{options[:shell] || "sh"} -c"
-                cmd = cmd.gsub(/[$\\`"]/) { |m| "\\#{m}" }
-                cmd = "\"#{cmd}\""
-              end
+            request_pty_if_necessary(channel) do |ch, success|
+              if success
+                logger.trace "executing command", ch[:server] if logger
+                cmd = replace_placeholders(command, ch)
 
-              command_line = [environment, shell, cmd].compact.join(" ")
+                if options[:shell] == false
+                  shell = nil
+                else
+                  shell = [options.fetch(:shell, "sh"), "-c"].join(" ")
+                  cmd = cmd.gsub(/[$\\`"]/) { |m| "\\#{m}" }
+                  cmd = "\"#{cmd}\""
+                end
 
-              ch.exec(command_line)
-              ch.send_data(options[:data]) if options[:data]
-            end
+                command_line = [environment, options[:command_prefix], shell, cmd].compact.join(" ")
 
-            if options[:pty]
-              channel.request_pty(:want_reply => true)
-              channel.on_success(&execute_command)
-              channel.on_failure do |ch|
+                ch.exec(command_line)
+                ch.send_data(options[:data]) if options[:data]
+              else
                 # just log it, don't actually raise an exception, since the
                 # process method will see that the status is not zero and will
                 # raise an exception then.
                 logger.important "could not open channel", ch[:server] if logger
                 ch.close
               end
-            else
-              execute_command.call(channel)
             end
-              
+
             channel.on_data do |ch, data|
               @callback[ch, :out, data] if @callback
             end
@@ -124,8 +108,8 @@ module Capistrano
               @callback[ch, :err, data] if @callback
             end
 
-            channel.on_request do |ch, request, reply, data|
-              ch[:status] = data.read_long if request == "exit-status"
+            channel.on_request("exit-status") do |ch, data|
+              ch[:status] = data.read_long
             end
 
             channel.on_close do |ch|
@@ -135,6 +119,16 @@ module Capistrano
         end
       end
 
+      def request_pty_if_necessary(channel)
+        if options[:pty]
+          channel.request_pty do |ch, success|
+            yield ch, success
+          end
+        else
+          yield channel, true
+        end
+      end
+
       def replace_placeholders(command, channel)
         command.gsub(/\$CAPISTRANO:HOST\$/, channel[:host])
       end

data/lib/capistrano/configuration/actions/file_transfer.rb

@@ -1,4 +1,4 @@
-require 'capistrano/upload'
+require 'capistrano/transfer'
 
 module Capistrano
   class Configuration
@@ -9,23 +9,31 @@ module Capistrano
         # by the current task. If <tt>:mode</tt> is specified it is used to
         # set the mode on the file.
         def put(data, path, options={})
-          execute_on_servers(options) do |servers|
-            targets = servers.map { |s| sessions[s] }
-            Upload.process(targets, path, :data => data, :mode => options[:mode], :logger => logger)
-          end
+          opts = options.dup
+          opts[:permissions] = opts.delete(:mode)
+          upload(StringIO.new(data), path, opts)
         end
     
-        # Get file remote_path from FIRST server targetted by
+        # Get file remote_path from FIRST server targeted by
         # the current task and transfer it to local machine as path.
         #
         # get "#{deploy_to}/current/log/production.log", "log/production.log.web"
-        def get(remote_path, path, options = {})
-          execute_on_servers(options.merge(:once => true)) do |servers|
-            logger.info "downloading `#{servers.first.host}:#{remote_path}' to `#{path}'"
-            sftp = sessions[servers.first].sftp
-            sftp.connect unless sftp.state == :open
-            sftp.get_file remote_path, path
-            logger.debug "download finished" 
+        def get(remote_path, path, options={}, &block)
+          download(remote_path, path, options.merge(:once => true), &block)
+        end
+
+        def upload(from, to, options={}, &block)
+          transfer(:up, from, to, options, &block)
+        end
+
+        def download(from, to, options={}, &block)
+          transfer(:down, from, to, options, &block)
+        end
+
+        def transfer(direction, from, to, options={}, &block)
+          execute_on_servers(options) do |servers|
+            targets = servers.map { |s| sessions[s] }
+            Transfer.process(direction, from, to, targets, options.merge(:logger => logger), &block)
           end
         end
 

data/lib/capistrano/configuration/actions/invocation.rb

@@ -70,7 +70,7 @@ module Capistrano
           as = options.delete(:as)
 
           user = as && "-u #{as}"
-          command = [fetch(:sudo, "sudo"), "-p '#{sudo_prompt}'", user, command].compact.join(" ")
+          options[:command_prefix] = [fetch(:sudo, "sudo"), "-p '#{sudo_prompt}'", user].compact.join(" ")
 
           run(command, options, &sudo_behavior_callback(block))
         end

data/lib/capistrano/configuration/connections.rb

@@ -1,7 +1,7 @@
-
 require 'enumerator'
-require 'capistrano/gateway'
+require 'net/ssh/gateway'
 require 'capistrano/ssh'
+require 'capistrano/errors'
 
 module Capistrano
   class Configuration
@@ -11,8 +11,6 @@ module Capistrano
         base.send :alias_method, :initialize, :initialize_with_connections
       end
 
-      # An adaptor for making the SSH interface look and act like that of the
-      # Gateway class.
       class DefaultConnectionFactory #:nodoc:
         def initialize(options)
           @options = options
@@ -23,6 +21,27 @@ module Capistrano
         end
       end
 
+      class GatewayConnectionFactory #:nodoc:
+        def initialize(gateway, options)
+          Thread.abort_on_exception = true
+          server = ServerDefinition.new(gateway)
+
+          @options = options
+          @gateway = SSH.connection_strategy(server, options) do |host, user, connect_options|
+            Net::SSH::Gateway.new(host, user, connect_options)
+          end
+        end
+
+        def connect_to(server)
+          @options[:logger].debug "establishing connection to `#{server}' via gateway" if @options[:logger]
+          local_host = ServerDefinition.new("127.0.0.1", :user => server.user, :port => @gateway.open(server.host, server.port || 22))
+          session = SSH.connect(local_host, @options)
+          session.xserver = server
+          @options[:logger].trace "connected: `#{server}' (via gateway)" if @options[:logger]
+          session
+        end
+      end
+
       # A hash of the SSH sessions that are currently open and available.
       # Because sessions are constructed lazily, this will only contain
       # connections to those servers that have been the targets of one or more
@@ -61,7 +80,7 @@ module Capistrano
         @connection_factory ||= begin
           if exists?(:gateway)
             logger.debug "establishing connection to gateway `#{fetch(:gateway)}'"
-            Gateway.new(ServerDefinition.new(fetch(:gateway)), self)
+            GatewayConnectionFactory.new(fetch(:gateway), self)
           else
             DefaultConnectionFactory.new(self)
           end
@@ -72,22 +91,13 @@ module Capistrano
       def establish_connections_to(servers)
         failed_servers = []
 
-        # This attemps to work around the problem where SFTP uploads hang
-        # for some people. A bit of investigating seemed to reveal that the
-        # hang only occurred when the SSH connections were established async,
-        # so this setting allows people to at least work around the problem.
-        if fetch(:synchronous_connect, false)
-          logger.trace "synchronous_connect: true"
-          Array(servers).each { |server| safely_establish_connection_to(server, failed_servers) }
-        else
-          # force the connection factory to be instantiated synchronously,
-          # otherwise we wind up with multiple gateway instances, because
-          # each connection is done in parallel.
-          connection_factory
+        # force the connection factory to be instantiated synchronously,
+        # otherwise we wind up with multiple gateway instances, because
+        # each connection is done in parallel.
+        connection_factory
 
-          threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) }
-          threads.each { |t| t.join }
-        end
+        threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) }
+        threads.each { |t| t.join }
 
         if failed_servers.any?
           errors = failed_servers.map { |h| "#{h[:server]} (#{h[:error].class}: #{h[:error].message})" }

data/lib/capistrano/errors.rb

@@ -10,6 +10,6 @@ module Capistrano
   end
 
   class ConnectionError < RemoteError; end
-  class UploadError < RemoteError; end
+  class TransferError < RemoteError; end
   class CommandError < RemoteError; end
 end

data/lib/capistrano/processable.rb

@@ -0,0 +1,53 @@
+module Capistrano
+  module Processable
+    module SessionAssociation
+      def self.on(exception, session)
+        unless exception.respond_to?(:session)
+          exception.extend(self)
+          exception.session = session
+        end
+
+        return exception
+      end
+
+      attr_accessor :session
+    end
+
+    def process_iteration(wait=nil, &block)
+      ensure_each_session { |session| session.preprocess }
+
+      return false if block && !block.call(self)
+
+      readers = sessions.map { |session| session.listeners.keys }.flatten.reject { |io| io.closed? }
+      writers = readers.select { |io| io.respond_to?(:pending_write?) && io.pending_write? }
+
+      if readers.any? || writers.any?
+        readers, writers, = IO.select(readers, writers, nil, wait)
+      end
+
+      if readers
+        ensure_each_session do |session|
+          ios = session.listeners.keys
+          session.postprocess(ios & readers, ios & writers)
+        end
+      end
+
+      true
+    end
+
+    def ensure_each_session
+      errors = []
+
+      sessions.each do |session|
+        begin
+          yield session
+        rescue Exception => error
+          errors << SessionAssociation.on(error, session)
+        end
+      end
+
+      raise errors.first if errors.any?
+      sessions
+    end
+  end
+end

data/lib/capistrano/recipes/deploy/remote_dependency.rb

@@ -15,6 +15,12 @@ module Capistrano
         self
       end
 
+      def file(path, options={})
+        @message ||= "`#{path}' is not a file"
+        try("test -f #{path}", options)
+        self
+      end
+
       def writable(path, options={})
         @message ||= "`#{path}' is not writable"
         try("test -w #{path}", options)

data/lib/capistrano/recipes/deploy/scm/git.rb

@@ -24,14 +24,6 @@ module Capistrano
       #   * Supports :scm_command, :scm_password, :scm_passphrase Capistrano
       #     directives.
       #
-      # REQUIREMENTS
-      # ------------
-      #
-      # Git is required to be installed on your remote machine(s), because a
-      # clone and checkout is done to get the code up there.  This is the way
-      # I prefer to deploy; there is no alternative to this, so :deploy_via
-      # is ignored.
-      #
       # CONFIGURATION
       # -------------
       #
@@ -100,13 +92,24 @@ module Capistrano
       #
       #   set :git_shallow_clone, 1
       #
+      # For those that don't like to leave your entire repository on
+      # your production server you can:
+      #
+      #   set :deploy_via, :export
+      #
+      # To deploy from a local repository:
+      #
+      #   set :repository, "file://."
+      #   set :deploy_via, :copy
+      #
       # AUTHORS
       # -------
       #
       # Garry Dolley http://scie.nti.st
       # Contributions by Geoffrey Grosenbach http://topfunky.com
       #              Scott Chacon http://jointheconversation.org
-      #                      and Alex Arnell http://twologic.com
+      #                          Alex Arnell http://twologic.com
+      #                                   and Phillip Goldenburg
 
       class Git < Base
         # Sets the default command name for this SCM on your *local* machine.
@@ -153,6 +156,12 @@ module Capistrano
 
           execute.join(" && ")
         end
+        
+        # An expensive export. Performs a checkout as above, then
+        # removes the repo.
+        def export(revision, destination)
+          checkout(revision, destination) << " && rm -Rf #{destination}/.git"
+        end
 
         # Merges the changes to 'head' since the last fetch, for remote_cache
         # deployment strategy
@@ -175,7 +184,7 @@ module Capistrano
           end
 
           # since we're in a local branch already, just reset to specified revision rather than merge
-          execute << "#{git} fetch #{remote} && #{git} reset --hard #{revision}"
+          execute << "#{git} fetch --tags #{remote} && #{git} reset --hard #{revision}"
 
           if configuration[:git_enable_submodules]
             execute << "#{git} submodule init"
@@ -200,7 +209,13 @@ module Capistrano
         # Getting the actual commit id, in case we were passed a tag
         # or partial sha or something - it will return the sha if you pass a sha, too
         def query_revision(revision)
-          yield(scm('rev-parse', revision)).chomp
+          return revision if revision =~ /^[0-9a-f]{40}$/
+          command = scm('ls-remote', repository, revision)
+          result = yield(command)
+          revdata = result.split("\t")
+          newrev = revdata[0]
+          raise "Unable to resolve revision for #{revision}" unless newrev =~ /^[0-9a-f]{40}$/
+          return newrev
         end
 
         def command

data/lib/capistrano/recipes/deploy/scm/none.rb

@@ -0,0 +1,44 @@
+require 'capistrano/recipes/deploy/scm/base'
+
+module Capistrano
+  module Deploy
+    module SCM
+
+      # A trivial SCM wrapper for representing the current working directory
+      # as a repository. Obviously, not all operations are available for this
+      # SCM, but it works sufficiently for use with the "copy" deployment
+      # strategy.
+      #
+      # Use of this module is _not_ recommended; in general, it is good
+      # practice to use some kind of source code management even for anything
+      # you are wanting to deploy. However, this module is provided in
+      # acknowledgement of the cases where trivial deployment of your current
+      # working directory is desired.
+      #
+      #   set :repository, "."
+      #   set :scm, :none
+      #   set :deploy_via, :copy
+      class None < Base
+        # No versioning, thus, no head. Returns the empty string.
+        def head
+          ""
+        end
+
+        # Simply does a copy from the :repository directory to the
+        # :destination directory.
+        def checkout(revision, destination)
+          "cp -R #{repository} #{destination}"
+        end
+
+        alias_method :export, :checkout
+
+        # No versioning, so this just returns the argument, with no
+        # modification.
+        def query_revision(revision)
+          revision
+        end
+      end
+
+    end
+  end
+end

data/lib/capistrano/recipes/deploy/strategy/base.rb

@@ -46,6 +46,12 @@ module Capistrano
             end
           end
 
+          # A wrapper for Kernel#system that logs the command being executed.
+          def system(*args)
+            logger.trace "executing locally: #{args.join(' ')}"
+            super
+          end
+
         private
 
           def logger

data/lib/capistrano/recipes/deploy/strategy/copy.rb

@@ -15,7 +15,26 @@ module Capistrano
       # of the source code. If you would rather use the export operation,
       # you can set the :copy_strategy variable to :export.
       #
-      # This deployment strategy supports a special variable,
+      #   set :copy_strategy, :export
+      #
+      # For even faster deployments, you can set the :copy_cache variable to
+      # true. This will cause deployments to do a new checkout of your
+      # repository to a new directory, and then copy that checkout. Subsequent
+      # deploys will just resync that copy, rather than doing an entirely new
+      # checkout. Additionally, you can specify file patterns to exclude from
+      # the copy when using :copy_cache; just set the :copy_exclude variable
+      # to a file glob (or an array of globs).
+      #
+      #   set :copy_cache, true
+      #   set :copy_exclude, ".git/*"
+      #
+      # Note that :copy_strategy is ignored when :copy_cache is set. Also, if
+      # you want the copy cache put somewhere specific, you can set the variable
+      # to the path you want, instead of merely 'true':
+      #
+      #   set :copy_cache, "/tmp/caches/myapp"
+      #
+      # This deployment strategy also supports a special variable,
       # :copy_compression, which must be one of :gzip, :bz2, or
       # :zip, and which specifies how the source should be compressed for
       # transmission to each host.
@@ -25,8 +44,44 @@ module Capistrano
         # servers, and uncompresses it on each of them into the deployment
         # directory.
         def deploy!
-          logger.debug "getting (via #{copy_strategy}) revision #{revision} to #{destination}"
-          system(command)
+          if copy_cache
+            if File.exists?(copy_cache)
+              logger.debug "refreshing local cache to revision #{revision} at #{copy_cache}"
+              system(source.sync(revision, copy_cache))
+            else
+              logger.debug "preparing local cache at #{copy_cache}"
+              system(source.checkout(revision, copy_cache))
+            end
+
+            logger.debug "copying cache to deployment staging area #{destination}"
+            Dir.chdir(copy_cache) do
+              FileUtils.mkdir_p(destination)
+              queue = Dir.glob("*", File::FNM_DOTMATCH)
+              while queue.any?
+                item = queue.shift
+                name = File.basename(item)
+
+                next if name == "." || name == ".."
+                next if copy_exclude.any? { |pattern| File.fnmatch(pattern, item) }
+
+                if File.directory?(item)
+                  queue += Dir.glob("#{item}/*", File::FNM_DOTMATCH)
+                  FileUtils.mkdir(File.join(destination, item))
+                else
+                  FileUtils.ln(File.join(copy_cache, item), File.join(destination, item))
+                end
+              end
+            end
+          else
+            logger.debug "getting (via #{copy_strategy}) revision #{revision} to #{destination}"
+            system(command)
+
+            if copy_exclude.any?
+              logger.debug "processing exclusions..."
+              copy_exclude.each { |pattern| FileUtils.rm_rf(File.join(destination, pattern)) }
+            end
+          end
+
           File.open(File.join(destination, "REVISION"), "w") { |f| f.puts(revision) }
 
           logger.trace "compressing #{destination} to #{filename}"
@@ -48,8 +103,24 @@ module Capistrano
           end
         end
 
+        # Returns the location of the local copy cache, if the strategy should
+        # use a local cache + copy instead of a new checkout/export every
+        # time. Returns +nil+ unless :copy_cache has been set. If :copy_cache
+        # is +true+, a default cache location will be returned.
+        def copy_cache
+          @copy_cache ||= configuration[:copy_cache] == true ?
+            File.join(Dir.tmpdir, configuration[:application]) :
+            configuration[:copy_cache]
+        end
+
         private
 
+          # Specify patterns to exclude from the copy. This is only valid
+          # when using a local cache.
+          def copy_exclude
+            @copy_exclude ||= Array(configuration.fetch(:copy_exclude, []))
+          end
+
           # Returns the basename of the release_path, which will be used to
           # name the local copy and archive file.
           def destination