capistrano 2.0.0 → 2.15.2

data/lib/capistrano/configuration/execution.rb

@@ -8,22 +8,11 @@ module Capistrano
         base.send :alias_method, :initialize, :initialize_with_execution
       end
 
-      # The call stack of the tasks. The currently executing task may inspect
-      # this to see who its caller was. The current task is always the last
-      # element of this stack.
-      attr_reader :task_call_frames
-
-      # The stack of tasks that have registered rollback handlers within the
-      # current transaction. If this is nil, then there is no transaction
-      # that is currently active.
-      attr_reader :rollback_requests
-
       # A struct for representing a single instance of an invoked task.
       TaskCallFrame = Struct.new(:task, :rollback)
 
       def initialize_with_execution(*args) #:nodoc:
         initialize_without_execution(*args)
-        @task_call_frames = []
       end
       private :initialize_with_execution
 
@@ -32,6 +21,25 @@ module Capistrano
         !rollback_requests.nil?
       end
 
+      # The call stack of the tasks. The currently executing task may inspect
+      # this to see who its caller was. The current task is always the last
+      # element of this stack.
+      def task_call_frames
+        Thread.current[:task_call_frames] ||= []
+      end
+
+
+      # The stack of tasks that have registered rollback handlers within the
+      # current transaction. If this is nil, then there is no transaction
+      # that is currently active.
+      def rollback_requests
+        Thread.current[:rollback_requests]
+      end
+
+      def rollback_requests=(rollback_requests)
+        Thread.current[:rollback_requests] = rollback_requests
+      end
+
       # Invoke a set of tasks in a transaction. If any task fails (raises an
       # exception), all tasks executed within the transaction are inspected to
       # see if they have an associated on_rollback hook, and if so, that hook
@@ -44,14 +52,14 @@ module Capistrano
 
         logger.info "transaction: start"
         begin
-          @rollback_requests = []
+          self.rollback_requests = []
           yield
           logger.info "transaction: commit"
         rescue Object => e
           rollback!
           raise
         ensure
-          @rollback_requests = nil
+          self.rollback_requests = nil
         end
       end
 
@@ -60,8 +68,9 @@ module Capistrano
       # hook will be executed.
       def on_rollback(&block)
         if transaction?
+          # don't note a new rollback request if one has already been set
+          rollback_requests << task_call_frames.last unless task_call_frames.last.rollback
           task_call_frames.last.rollback = block
-          rollback_requests << task_call_frames.last
         end
       end
 
@@ -72,12 +81,12 @@ module Capistrano
         task_call_frames.last.task
       end
 
-      # Executes the task with the given name, including the before and after
-      # hooks.
+      # Executes the task with the given name, without invoking any associated
+      # callbacks.
       def execute_task(task)
         logger.debug "executing `#{task.fully_qualified_name}'"
         push_task_call_frame(task)
-        task.namespace.instance_eval(&task.body)
+        invoke_task_directly(task)
       ensure
         pop_task_call_frame
       end
@@ -98,6 +107,8 @@ module Capistrano
     protected
 
       def rollback!
+        return if Thread.current[:rollback_requests].nil?
+
         # throw the task back on the stack so that roles are properly
         # interpreted in the scope of the task in question.
         rollback_requests.reverse.each do |frame|
@@ -121,6 +132,11 @@ module Capistrano
       def pop_task_call_frame
         task_call_frames.pop
       end
+
+      # Invokes the task's body directly, without setting up the call frame.
+      def invoke_task_directly(task)
+        task.namespace.instance_eval(&task.body)
+      end
     end
   end
-end
+end

data/lib/capistrano/configuration/loading.rb

@@ -25,6 +25,28 @@ module Capistrano
         def instance=(config)
           Thread.current[:capistrano_configuration] = config
         end
+
+        # Used internally by Capistrano to track which recipes have been loaded
+        # via require, so that they may be successfully reloaded when require
+        # is called again.
+        def recipes_per_feature
+          @recipes_per_feature ||= {}
+        end
+
+        # Used internally to determine what the current "feature" being
+        # required is. This is used to track which files load which recipes
+        # via require.
+        def current_feature
+          Thread.current[:capistrano_current_feature]
+        end
+
+        # Used internally to specify the current file being required, so that
+        # any recipes loaded by that file can be remembered. This allows
+        # recipes loaded via require to be correctly reloaded in different
+        # Configuration instances in the same Ruby instance.
+        def current_feature=(feature)
+          Thread.current[:capistrano_current_feature] = feature
+        end
       end
 
       # The load paths used for locating recipe files.
@@ -33,6 +55,7 @@ module Capistrano
       def initialize_with_loading(*args) #:nodoc:
         initialize_without_loading(*args)
         @load_paths = [".", File.expand_path(File.join(File.dirname(__FILE__), "../recipes"))]
+        @loaded_features = []
       end
       private :initialize_with_loading
 
@@ -66,9 +89,11 @@ module Capistrano
           load_from_file(options[:file], options[:name])
 
         elsif options[:string]
+          remember_load(options) unless options[:reloading]
           instance_eval(options[:string], options[:name] || "<eval>")
 
         elsif options[:proc]
+          remember_load(options) unless options[:reloading]
           instance_eval(&options[:proc])
 
         else
@@ -80,12 +105,62 @@ module Capistrano
       # with the exception that it sets the receiver as the "current" configuration
       # so that third-party task bundles can include themselves relative to
       # that configuration.
+      #
+      # This is a bit more complicated than an initial review would seem to
+      # necessitate, but the use case that complicates things is this: An
+      # advanced user wants to embed capistrano, and needs to instantiate
+      # more than one capistrano configuration at a time. They also want each
+      # configuration to require a third-party capistrano extension. Using a
+      # naive require implementation, this would allow the first configuration
+      # to successfully load the third-party extension, but the require would
+      # fail for the second configuration because the extension has already
+      # been loaded.
+      #
+      # To work around this, we do a few things:
+      #
+      # 1. Each time a 'require' is invoked inside of a capistrano recipe,
+      #    we remember the arguments (see "current_feature").
+      # 2. Each time a 'load' is invoked inside of a capistrano recipe, and
+      #    "current_feature" is not nil (meaning we are inside of a pending
+      #    require) we remember the options (see "remember_load" and
+      #    "recipes_per_feature").
+      # 3. Each time a 'require' is invoked inside of a capistrano recipe,
+      #    we check to see if this particular configuration has ever seen these
+      #    arguments to require (see @loaded_features), and if not, we proceed
+      #    as if the file had never been required. If the superclass' require
+      #    returns false (meaning, potentially, that the file has already been
+      #    required), then we look in the recipes_per_feature collection and
+      #    load any remembered recipes from there.
+      #
+      # It's kind of a bear, but it works, and works transparently. Note that
+      # a simpler implementation would just muck with $", allowing files to be
+      # required multiple times, but that will cause warnings (and possibly
+      # errors) if the file to be required contains constant definitions and
+      # such, alongside (or instead of) capistrano recipe definitions.
       def require(*args) #:nodoc:
-        original, self.class.instance = self.class.instance, self
-        super
-      ensure
-        # restore the original, so that require's can be nested
-        self.class.instance = original
+        # look to see if this specific configuration instance has ever seen
+        # these arguments to require before
+        if @loaded_features.include?(args)
+          return false
+        end
+
+        @loaded_features << args
+        begin
+          original_instance, self.class.instance = self.class.instance, self
+          original_feature, self.class.current_feature = self.class.current_feature, args
+
+          result = super
+          if !result # file has been required previously, load up the remembered recipes
+            list = self.class.recipes_per_feature[args] || []
+            list.each { |options| load(options.merge(:reloading => true)) }
+          end
+
+          return result
+        ensure
+          # restore the original, so that require's can be nested
+          self.class.instance = original_instance
+          self.class.current_feature = original_feature
+        end
       end
 
       private
@@ -93,7 +168,7 @@ module Capistrano
         # Load a recipe from the named file. If +name+ is given, the file will
         # be reported using that name.
         def load_from_file(file, name=nil)
-          file = find_file_in_load_path(file) unless file[0] == ?/
+          file = find_file_in_load_path(file) unless File.file?(file)
           load :string => File.read(file), :name => name || file
         end
 
@@ -107,6 +182,16 @@ module Capistrano
 
           raise LoadError, "no such file to load -- #{file}"
         end
+
+        # If a file is being required, the options associated with loading a
+        # recipe are remembered in the recipes_per_feature archive under the
+        # name of the file currently being required.
+        def remember_load(options)
+          if self.class.current_feature
+            list = (self.class.recipes_per_feature[self.class.current_feature] ||= [])
+            list << options
+          end
+        end
     end
   end
 end

data/lib/capistrano/configuration/log_formatters.rb

@@ -0,0 +1,75 @@
+# Add custom log formatters
+#
+# Passing a hash or a array of hashes with custom log formatters.
+#
+# Add the following to your deploy.rb or in your ~/.caprc
+#
+# == Example:
+#
+#   capistrano_log_formatters = [
+#     { :match => /command finished/,       :color => :hide,      :priority => 10, :prepend => "$$$" },
+#     { :match => /executing command/,      :color => :blue,      :priority => 10, :style => :underscore, :timestamp => true },
+#     { :match => /^transaction: commit$/,  :color => :magenta,   :priority => 10, :style => :blink },
+#     { :match => /git/,                    :color => :white,     :priority => 20, :style => :reverse }
+#   ]
+#
+#   format_logs capistrano_log_formatters
+#
+# You can call format_logs multiple times, with either a hash or an array of hashes.
+#
+# == Colors:
+#
+# :color can have the following values:
+#
+# * :hide  (hides the row completely)
+# * :none
+# * :black
+# * :red
+# * :green
+# * :yellow
+# * :blue
+# * :magenta
+# * :cyan
+# * :white
+#
+# == Styles:
+#
+# :style can have the following values:
+#
+# * :bright
+# * :dim
+# * :underscore
+# * :blink
+# * :reverse
+# * :hidden
+#
+#
+#  == Text alterations
+#
+# :prepend gives static text to be prepended to the output
+# :replace replaces the matched text in the output
+# :timestamp adds the current time before the output
+
+module Capistrano
+  class Configuration
+    module LogFormatters
+      def log_formatter(options)
+        if options.class == Array
+          options.each do |option|
+            Capistrano::Logger.add_formatter(option)
+          end
+        else
+          Capistrano::Logger.add_formatter(options)
+        end
+      end
+
+      def default_log_formatters(formatters)
+        default_formatters = [*formatters]
+      end
+
+      def disable_log_formatters
+        @logger.disable_formatters = true
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/namespaces.rb

@@ -32,6 +32,12 @@ module Capistrano
       end
       private :initialize_with_namespaces
 
+      # Returns the top-level namespace (the one with no parent).
+      def top
+        return parent.top if parent
+        return self
+      end
+
       # Returns the fully-qualified name of this namespace, or nil if the
       # namespace is at the top-level.
       def fully_qualified_name
@@ -61,7 +67,7 @@ module Capistrano
         raise ArgumentError, "expected a block" unless block_given?
 
         namespace_already_defined = namespaces.key?(name)
-        if all_methods.include?(name.to_s) && !namespace_already_defined
+        if all_methods.any? { |m| m.to_sym == name } && !namespace_already_defined
           thing = tasks.key?(name) ? "task" : "method"
           raise ArgumentError, "defining a namespace named `#{name}' would shadow an existing #{thing} with that name"
         end
@@ -86,17 +92,22 @@ module Capistrano
         raise ArgumentError, "expected a block" unless block_given?
 
         task_already_defined = tasks.key?(name)
-        if all_methods.include?(name.to_s) && !task_already_defined
+        if all_methods.any? { |m| m.to_sym == name } && !task_already_defined
           thing = namespaces.key?(name) ? "namespace" : "method"
           raise ArgumentError, "defining a task named `#{name}' would shadow an existing #{thing} with that name"
         end
 
-        tasks[name] = TaskDefinition.new(name, self, {:desc => next_description(:reset)}.merge(options), &block)
 
-        if !task_already_defined
-          metaclass = class << self; self; end
-          metaclass.send(:define_method, name) { execute_task(tasks[name]) }
-        end
+        task = TaskDefinition.new(name, self, {:desc => next_description(:reset)}.merge(options), &block)
+
+        define_task(task)
+      end
+
+      def define_task(task)
+        tasks[task.name] = task
+
+        metaclass = class << self; self; end
+        metaclass.send(:define_method, task.name) { execute_task(tasks[task.name]) }
       end
 
       # Find the task with the given name, where name is the fully-qualified
@@ -110,7 +121,8 @@ module Capistrano
 
         ns = self
         until parts.empty?
-          ns = ns.namespaces[parts.shift.to_sym]
+          next_part = parts.shift
+          ns = next_part.empty? ? nil : ns.namespaces[next_part.to_sym]
           return nil if ns.nil?
         end
 
@@ -144,7 +156,7 @@ module Capistrano
         return nil if parent.nil?
         return tasks[DEFAULT_TASK]
       end
-  
+
       # Returns the tasks in this namespace as an array of TaskDefinition
       # objects. If a non-false parameter is given, all tasks in all
       # namespaces under this namespace will be returned as well.
@@ -170,8 +182,8 @@ module Capistrano
             raise NotImplementedError, "roles cannot be defined in a namespace"
           end
 
-          def respond_to?(sym)
-            super || parent.respond_to?(sym)
+          def respond_to?(sym, include_priv=false)
+            super || parent.respond_to?(sym, include_priv)
           end
 
           def method_missing(sym, *args, &block)
@@ -182,9 +194,30 @@ module Capistrano
             end
           end
 
+          include Capistrano::Configuration::AliasTask
           include Capistrano::Configuration::Namespaces
           undef :desc, :next_description
         end
     end
   end
-end
+end
+
+module Kernel
+  class << self
+    alias_method :method_added_without_capistrano, :method_added
+
+    # Detect method additions to Kernel and remove them in the Namespace class
+    def method_added(name)
+      result = method_added_without_capistrano(name)
+      return result if self != Kernel
+
+      namespace = Capistrano::Configuration::Namespaces::Namespace
+
+      if namespace.method_defined?(name) && namespace.instance_method(name).owner == Kernel
+        namespace.send :undef_method, name
+      end
+
+      result
+    end
+  end
+end

data/lib/capistrano/configuration/roles.rb

@@ -1,4 +1,5 @@
 require 'capistrano/server_definition'
+require 'capistrano/role'
 
 module Capistrano
   class Configuration
@@ -15,7 +16,7 @@ module Capistrano
 
       def initialize_with_roles(*args) #:nodoc:
         initialize_without_roles(*args)
-        @roles = Hash.new { |h,k| h[k] = [] }
+        @roles = Hash.new { |h,k| h[k] = Role.new }
       end
 
       # Define a new role and its associated servers. You must specify at least
@@ -41,11 +42,36 @@ module Capistrano
       # that call to "role":
       #
       #   role :web, "web2", "web3", :user => "www", :port => 2345
-      def role(which, *args)
+      def role(which, *args, &block)
         options = args.last.is_a?(Hash) ? args.pop : {}
         which = which.to_sym
+
+        # The roles Hash is defined so that unrecognized keys always auto-initialize
+        # to a new Role instance (see the assignment in the initialize_with_roles method,
+        # above). However, we explicitly assign here so that role declarations will
+        # vivify the role object even if there are no server arguments. (Otherwise,
+        # role(:app) won't actually instantiate a Role object for :app.)
+        roles[which] ||= Role.new
+
+        roles[which].push(block, options) if block_given?
         args.each { |host| roles[which] << ServerDefinition.new(host, options) }
       end
+
+      # An alternative way to associate servers with roles. If you have a server
+      # that participates in multiple roles, this can be a DRYer way to describe
+      # the relationships. Pass the host definition as the first parameter, and
+      # the roles as the remaining parameters:
+      #
+      #   server "master.example.com", :web, :app
+      def server(host, *roles)
+        options = roles.last.is_a?(Hash) ? roles.pop : {}
+        raise ArgumentError, "you must associate a server with at least one role" if roles.empty?
+        roles.each { |name| role(name, host, options) }
+      end
+
+      def role_names_for_host(host)
+        roles.map {|role_name, role| role_name if role.include?(host) }.compact || []
+      end
     end
   end
 end

data/lib/capistrano/configuration/servers.rb

@@ -13,14 +13,22 @@ module Capistrano
       # The options hash may include a :hosts option (which should specify
       # an array of host names or ServerDefinition instances), a :roles
       # option (specifying an array of roles), an :only option (specifying
-      # a hash of key/value pairs that any matching server must match), and
-      # an :exception option (like :only, but the inverse).
+      # a hash of key/value pairs that any matching server must match),
+      # an :exception option (like :only, but the inverse), and a
+      # :skip_hostfilter option to ignore the HOSTFILTER environment variable
+      # described below.
       #
       # Additionally, if the HOSTS environment variable is set, it will take
       # precedence over any other options. Similarly, the ROLES environment
       # variable will take precedence over other options. If both HOSTS and
       # ROLES are given, HOSTS wins.
       #
+      # Yet additionally, if the HOSTFILTER environment variable is set, it
+      # will limit the result to hosts found in that (comma-separated) list.
+      #
+      # If the HOSTROLEFILTER environment variable is set, it will limit the
+      # result to hosts found in that (comma-separated) list of roles
+      #
       # Usage:
       #
       #   # return all known servers
@@ -34,23 +42,57 @@ module Capistrano
       #   # returns the given hosts, translated to ServerDefinition objects
       #   servers = find_servers :hosts => "jamis@example.host.com"
       def find_servers(options={})
+        return [] if options.key?(:hosts) && (options[:hosts].nil? || [] == options[:hosts])
+        return [] if options.key?(:roles) && (options[:roles].nil? || [] == options[:roles])
+
         hosts  = server_list_from(ENV['HOSTS'] || options[:hosts])
-        roles  = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys)
-        only   = options[:only] || {}
-        except = options[:except] || {}
 
         if hosts.any?
-          hosts.uniq
+          if options[:skip_hostfilter]
+            hosts.uniq
+          else
+            filter_server_list(hosts.uniq)
+          end
         else
-          servers = roles.inject([]) { |list, role| list.concat(self.roles[role]) }
+          roles = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys)
+          roles = roles & Array(options[:roles]) if preserve_roles && !options[:roles].nil?
+
+          only   = options[:only] || {}
+          except = options[:except] || {}
+
+          # If we don't have a def for a role it means its bogus, skip it so higher level can handle
+          servers = roles.inject([]) { |list, role| list.concat(self.roles[role] || []) }
           servers = servers.select { |server| only.all? { |key,value| server.options[key] == value } }
           servers = servers.reject { |server| except.any? { |key,value| server.options[key] == value } }
-          servers.uniq
+
+          if options[:skip_hostfilter]
+            servers.uniq
+          else
+            filter_server_list(servers.uniq)
+          end
         end
       end
 
     protected
 
+      def filter_server_list(servers)
+        return servers unless ENV['HOSTFILTER'] or ENV['HOSTROLEFILTER']
+        if ENV['HOSTFILTER']
+          filters = ENV['HOSTFILTER'].split(/,/)
+          servers.select { |server| filters.include?(server.host) }
+        elsif ENV['HOSTROLEFILTER']
+          filters = ENV['HOSTROLEFILTER'].split(/,/).map do |role|
+            local_roles = roles[role.to_sym]
+            if local_roles.is_a? Array
+              roles[role.to_sym]
+            else
+              roles[role.to_sym].servers
+            end
+          end.flatten
+          servers.select { |server| filters.include?(server) }
+        end
+      end
+
       def server_list_from(hosts)
         hosts = hosts.split(/,/) if String === hosts
         hosts = build_list(hosts)
@@ -62,7 +104,6 @@ module Capistrano
         roles = build_list(roles)
         roles.map do |role|
           role = String === role ? role.strip.to_sym : role
-          raise ArgumentError, "unknown role `#{role}'" unless self.roles.key?(role)
           role
         end
       end
@@ -72,4 +113,4 @@ module Capistrano
       end
     end
   end
-end
+end

data/lib/capistrano/configuration/variables.rb

@@ -111,8 +111,8 @@ module Capistrano
       end
       private :protect
 
-      def respond_to_with_variables?(sym) #:nodoc:
-        @variables.has_key?(sym) || respond_to_without_variables?(sym)
+      def respond_to_with_variables?(sym, include_priv=false) #:nodoc:
+        @variables.has_key?(sym.to_sym) || respond_to_without_variables?(sym, include_priv)
       end
 
       def method_missing_with_variables(sym, *args, &block) #:nodoc:
@@ -124,4 +124,4 @@ module Capistrano
       end
     end
   end
-end
+end

data/lib/capistrano/configuration.rb

@@ -1,9 +1,11 @@
 require 'capistrano/logger'
 
+require 'capistrano/configuration/alias_task'
 require 'capistrano/configuration/callbacks'
 require 'capistrano/configuration/connections'
 require 'capistrano/configuration/execution'
 require 'capistrano/configuration/loading'
+require 'capistrano/configuration/log_formatters'
 require 'capistrano/configuration/namespaces'
 require 'capistrano/configuration/roles'
 require 'capistrano/configuration/servers'
@@ -19,10 +21,13 @@ module Capistrano
   # define roles, and set configuration variables.
   class Configuration
     # The logger instance defined for this configuration.
-    attr_accessor :logger
+    attr_accessor :debug, :logger, :dry_run, :preserve_roles
 
-    def initialize #:nodoc:
-      @logger = Logger.new
+    def initialize(options={}) #:nodoc:
+      @debug = false
+      @dry_run = false
+      @preserve_roles = false
+      @logger = Logger.new(options)
     end
 
     # make the DSL easier to read when using lazy evaluation via lambdas
@@ -30,12 +35,23 @@ module Capistrano
 
     # The includes must come at the bottom, since they may redefine methods
     # defined in the base class.
-    include Connections, Execution, Loading, Namespaces, Roles, Servers, Variables
+    include AliasTask, Connections, Execution, Loading, LogFormatters, Namespaces, Roles, Servers, Variables
 
     # Mix in the actions
     include Actions::FileTransfer, Actions::Inspect, Actions::Invocation
 
     # Must mix last, because it hooks into previously defined methods
     include Callbacks
+
+    (self.instance_methods & Kernel.methods).select do |name|
+      # Select the instance methods owned by the Configuration class.
+      self.instance_method(name).owner.to_s.start_with?("Capistrano::Configuration")
+    end.select do |name|
+      # Of those, select methods that are being shadowed by the Kernel module in the Namespace class.
+      Namespaces::Namespace.method_defined?(name) && Namespaces::Namespace.instance_method(name).owner == Kernel
+    end.each do |name|
+      # Undefine the shadowed methods, since we want Namespace objects to defer handling to the Configuration object.
+      Namespaces::Namespace.send(:undef_method, name)
+    end
   end
 end