capistrano 1.4.2 → 2.0.0

data/lib/capistrano/cli/help.txt

@@ -0,0 +1,53 @@
+-----------------------------
+<%= color('Capistrano', :bold) %>
+-----------------------------
+
+Capistrano is a utility for automating the execution of commands across multiple remote machines. It was originally conceived as an aid to deploy Ruby on Rails web applications, but has since evolved to become a much more general-purpose tool.
+
+The command-line interface to Capistrano is via the `cap' command.
+
+	cap [ option ] ... action ...
+
+The following options are understood:
+
+  <%= color '-e, --explain TASK', :bold %>
+	Displays the extended description of the given task. Not all tasks will have an extended description, but for those that do, this can provide a wealth of additional usage information, such as describing environment variables or settings that can affect the execution of the task.
+
+  <%= color '-F, --default-config', :bold %>
+	By default, cap will search for a config file named `Capfile' or `capfile' in the current directory, or in any parent directory, and will automatically load it. However, if you specify the -f flag (see below), cap will use that file instead of the default config. If you want to use both the default config, and files loaded via -f, you can specify -F to force cap to search for and load the default config, even if additional files were specified via -f.
+
+  <%= color '-f, --file FILE', :bold %>
+	Causes the named file to be loaded. Capistrano will search both its own recipe directory, as well as the current directory, looking for the named file. An ".rb" extension is optional. The -f option may be given any number of times, but if it is given, it will take the place of the normal `Capfile' or `capfile' detection. Use -F if you want the default capfile to be loaded when you use -f.
+
+  <%= color '-H, --long-help', :bold %>
+	Displays this document and exits.
+
+  <%= color '-h, --help', :bold %>
+	Shows a brief summary of these options and exits.
+
+  <%= color '-p, --password', :bold %>
+	Normally, cap will prompt for the password on-demand, the first time it is needed. This can make it hard to walk away from Capistrano, since you might not know if it will prompt for a password down the road. In such cases, you can use the -p option to force cap to prompt for the password immediately.
+
+  <%= color '-q, --quiet', :bold %>
+	Display only critical error messages. All other output is suppressed.
+
+  <%= color '-S, --set-before NAME=VALUE', :bold %>
+	Sets the given variable to the given value, before loading any recipe files. This is useful if you have a recipe file that depends on a certain variable being set, at the time it is loaded.
+
+  <%= color '-s, --set NAME=VALUE', :bold %>
+	Sets the given variable to the given value, after loading all recipe files. This is useful when you want to override the value of a variable which is used in a task. Note that this will set the variables too late for them to affect conditions that are executed as the recipes are loaded.
+
+  <%= color '-T, --tasks', :bold %>
+	Displays the list of all tasks in all loaded recipe files. If a task has no description, or if the description starts with the [internal] tag, the task will not be listed unless you also specify -v.
+
+  <%= color '-V, --version', :bold %>
+	Shows the current Capistrano version number and exits.
+
+  <%= color '-v, --verbose', :bold %>
+	Increase the verbosity. You can specify this option up to three times to further increase verbosity. By default, cap will use maximum verbosity, but if you specify an explicit verbosity, that will be used instead. See also -q.
+
+  <%= color '-X, --skip-system-config', :bold %>
+	By default, cap will look for and (if it exists) load the global system configuration file located in /etc/capistrano.conf. If you don't want cap to load that file, give this option.
+
+  <%= color '-x, --skip-user-config', :bold %>
+	By default, cap will look for and (if it exists) load the user-specific configuration file located in $HOME/.caprc. If you don't want cap to load that file, give this option.

data/lib/capistrano/cli/options.rb

@@ -0,0 +1,183 @@
+require 'optparse'
+
+module Capistrano
+  class CLI
+    module Options
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Return a new CLI instance with the given arguments pre-parsed and
+        # ready for execution.
+        def parse(args)
+          cli = new(args)
+          cli.parse_options!
+          cli
+        end
+      end
+
+      # The hash of (parsed) command-line options
+      attr_reader :options
+
+      # Return an OptionParser instance that defines the acceptable command
+      # line switches for Capistrano, and what their corresponding behaviors
+      # are.
+      def option_parser #:nodoc:
+        @option_parser ||= OptionParser.new do |opts|
+          opts.banner = "Usage: #{File.basename($0)} [options] action ..."
+
+          opts.on("-e", "--explain TASK",
+            "Displays help (if available) for the task."
+          ) { |value| options[:explain] = value }
+
+          opts.on("-F", "--default-config",
+            "Always use default config, even with -f."
+          ) { options[:default_config] = true }
+
+          opts.on("-f", "--file FILE",
+            "A recipe file to load. May be given more than once."
+          ) { |value| options[:recipes] << value }
+
+          opts.on("-H", "--long-help", "Explain these options.") do
+            long_help
+            exit
+          end
+
+          opts.on("-h", "--help", "Display this help message.") do
+            puts opts
+            exit
+          end
+
+          opts.on("-p", "--password",
+            "Immediately prompt for the password."
+          ) { options[:password] = nil }
+
+          opts.on("-q", "--quiet",
+            "Make the output as quiet as possible (default)"
+          ) { options[:verbose] = 0 }
+
+          opts.on("-S", "--set-before NAME=VALUE",
+            "Set a variable before the recipes are loaded."
+          ) do |pair|
+            name, value = pair.split(/=/, 2)
+            options[:pre_vars][name.to_sym] = value
+          end
+
+          opts.on("-s", "--set NAME=VALUE",
+            "Set a variable after the recipes are loaded."
+          ) do |pair|
+            name, value = pair.split(/=/, 2)
+            options[:vars][name.to_sym] = value
+          end
+
+          opts.on("-T", "--tasks",
+            "List all tasks in the loaded recipe files."
+          ) do 
+            options[:tasks] = true
+            options[:verbose] ||= 0
+          end
+
+          opts.on("-V", "--version",
+            "Display the Capistrano version, and exit."
+          ) do
+            require 'capistrano/version'
+            puts "Capistrano v#{Capistrano::Version::STRING}"
+            exit
+          end
+
+          opts.on("-v", "--verbose",
+            "Be more verbose. May be given more than once."
+          ) { options[:verbose] ||= 0; options[:verbose] += 1 }
+
+          opts.on("-X", "--skip-system-config",
+            "Don't load the system config file (capistrano.conf)"
+          ) { options.delete(:sysconf) }
+
+          opts.on("-x", "--skip-user-config",
+            "Don't load the user config file (.caprc)"
+          ) { options.delete(:dotfile) }
+        end
+      end
+
+      # If the arguments to the command are empty, this will print the
+      # allowed options and exit. Otherwise, it will parse the command
+      # line and set up any default options.
+      def parse_options! #:nodoc:
+        @options = { :recipes => [], :actions => [],
+          :vars => {}, :pre_vars => {},
+          :sysconf => default_sysconf, :dotfile => default_dotfile }
+
+        if args.empty?
+          warn "Please specify at least one action to execute."
+          warn option_parser
+          exit
+        end
+
+        option_parser.parse!(args)
+
+        # if no verbosity has been specified, be verbose
+        options[:verbose] = 3 if !options.has_key?(:verbose)
+
+        look_for_default_recipe_file! if options[:default_config] || options[:recipes].empty?
+        extract_environment_variables!
+
+        options[:actions].concat(args)
+
+        password = options.has_key?(:password)
+        options[:password] = Proc.new { self.class.password_prompt }
+        options[:password] = options[:password].call if password
+      end
+
+      # Extracts name=value pairs from the remaining command-line arguments
+      # and assigns them as environment variables.
+      def extract_environment_variables! #:nodoc:
+        args.delete_if do |arg|
+          next unless arg.match(/^(\w+)=(.*)$/)
+          ENV[$1] = $2
+        end
+      end
+
+      # Looks for a default recipe file in the current directory.
+      def look_for_default_recipe_file! #:nodoc:
+        current = Dir.pwd
+
+        loop do
+          %w(Capfile capfile).each do |file|
+            if File.file?(file)
+              options[:recipes] << file
+              return
+            end
+          end
+
+          pwd = Dir.pwd
+          Dir.chdir("..")
+          break if pwd == Dir.pwd # if changing the directory made no difference, then we're at the top
+        end
+
+        Dir.chdir(current)
+      end
+
+      def default_sysconf #:nodoc:
+        File.join(sysconf_directory, "capistrano.conf")
+      end
+      
+      def default_dotfile #:nodoc:
+        File.join(home_directory, ".caprc")
+      end
+
+      def sysconf_directory #:nodoc:
+        # TODO if anyone cares, feel free to submit a patch that uses a more
+        # appropriate location for this file in Windows.
+        ENV["SystemRoot"] || '/etc'
+      end
+      
+      def home_directory #:nodoc:
+        ENV["HOME"] ||
+          (ENV["HOMEPATH"] && "#{ENV["HOMEDRIVE"]}#{ENV["HOMEPATH"]}") ||
+          "/"
+      end
+
+    end
+  end
+end

data/lib/capistrano/cli/ui.rb

@@ -0,0 +1,28 @@
+require 'highline'
+
+# work around problem where HighLine detects an eof on $stdin and raises an
+# error.
+HighLine.track_eof = false
+
+module Capistrano
+  class CLI
+    module UI
+      def self.included(base) #:nodoc:
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Return the object that provides UI-specific methods, such as prompts
+        # and more.
+        def ui
+          @ui ||= HighLine.new
+        end
+
+        # Prompt for a password using echo suppression.
+        def password_prompt(prompt="Password: ")
+          ui.ask(prompt) { |q| q.echo = false }
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/command.rb

@@ -1,28 +1,36 @@
+require 'capistrano/errors'
+
 module Capistrano
 
   # This class encapsulates a single command to be executed on a set of remote
   # machines, in parallel.
   class Command
-    class Error < RuntimeError; end
+    attr_reader :command, :sessions, :options
 
-    attr_reader :servers, :command, :options, :actor
+    def self.process(command, sessions, options={}, &block)
+      new(command, sessions, options, &block).process!
+    end
 
-    def initialize(servers, command, callback, options, actor) #:nodoc:
-      @servers = servers
-      @command = extract_environment(options) + command.strip.gsub(/\r?\n/, "\\\n")
-      @callback = callback
+    # Instantiates a new command object. The +command+ must be a string
+    # containing the command to execute. +sessions+ is an array of Net::SSH
+    # session instances, and +options+ must be a hash containing any of the
+    # following keys:
+    #
+    # * +logger+: (optional), a Capistrano::Logger instance
+    # * +data+: (optional), a string to be sent to the command via it's stdin
+    # * +env+: (optional), a string or hash to be interpreted as environment
+    #   variables that should be defined for this command invocation.
+    def initialize(command, sessions, options={}, &block)
+      @command = command.strip.gsub(/\r?\n/, "\\\n")
+      @sessions = sessions
       @options = options
-      @actor = actor
+      @callback = block
       @channels = open_channels
     end
 
-    def logger #:nodoc:
-      actor.logger
-    end
-
     # Processes the command in parallel on all specified hosts. If the command
     # fails (non-zero return code) on any of the hosts, this will raise a
-    # RuntimeError.
+    # Capistrano::CommandError.
     def process!
       since = Time.now
       loop do
@@ -41,10 +49,13 @@ module Capistrano
         sleep 0.01 # a brief respite, to keep the CPU from going crazy
       end
 
-      logger.trace "command finished"
+      logger.trace "command finished" if logger
 
-      if failed = @channels.detect { |ch| ch[:status] != 0 }
-        raise Error, "command #{@command.inspect} failed on #{failed[:host]}"
+      if (failed = @channels.select { |ch| ch[:status] != 0 }).any?
+        hosts = failed.map { |ch| ch[:server] }
+        error = CommandError.new("command #{command.inspect} failed on #{hosts.join(',')}")
+        error.hosts = hosts
+        raise error
       end
 
       self
@@ -60,21 +71,33 @@ module Capistrano
 
     private
 
+      def logger
+        options[:logger]
+      end
+
       def open_channels
-        @servers.map do |server|
-          @actor.sessions[server].open_channel do |channel|
-            channel[:host] = server
-            channel[:actor] = @actor # so callbacks can access the actor instance
+        sessions.map do |session|
+          session.open_channel do |channel|
+            server = session.xserver
+
+            channel[:server] = server
+            channel[:host] = server.host
+            channel[:options] = options
             channel.request_pty :want_reply => true
 
             channel.on_success do |ch|
-              logger.trace "executing command", ch[:host]
-              ch.exec command
-              ch.send_data options[:data] if options[:data]
+              logger.trace "executing command", ch[:server] if logger
+              escaped = replace_placeholders(command, ch).gsub(/[$\\`"]/) { |m| "\\#{m}" }
+              command_line = [environment, options[:shell] || "sh", "-c", "\"#{escaped}\""].compact.join(" ")
+              ch.exec(command_line)
+              ch.send_data(options[:data]) if options[:data]
             end
 
             channel.on_failure do |ch|
-              logger.important "could not open channel", ch[:host]
+              # 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
 
@@ -97,17 +120,27 @@ module Capistrano
         end
       end
 
+      def replace_placeholders(command, channel)
+        command.gsub(/\$CAPISTRANO:HOST\$/, channel[:host])
+      end
+
       # prepare a space-separated sequence of variables assignments
       # intended to be prepended to a command, so the shell sets
       # the environment before running the command.
       # i.e.: options[:env] = {'PATH' => '/opt/ruby/bin:$PATH',
       #                        'TEST' => '( "quoted" )'}
-      # extract_environment(options) returns:
-      # "TEST=(\ \"quoted\"\ ) PATH=/opt/ruby/bin:$PATH"
-      def extract_environment(options)
-        Array(options[:env]).inject("") do |string, (name, value)|
-          string << %|#{name}=#{value.gsub(/"/, "\\\"").gsub(/ /, "\\ ")} |
-        end
+      # environment returns:
+      # "env TEST=(\ \"quoted\"\ ) PATH=/opt/ruby/bin:$PATH"
+      def environment
+        return if options[:env].nil? || options[:env].empty?
+        @environment ||= if String === options[:env]
+            "env #{options[:env]}"
+          else
+            options[:env].inject("env") do |string, (name, value)|
+              value = value.to_s.gsub(/[ "]/) { |m| "\\#{m}" }
+              string << " #{name}=#{value}"
+            end
+          end
       end
   end
 end

data/lib/capistrano/configuration.rb

@@ -1,242 +1,41 @@
-require 'capistrano/actor'
 require 'capistrano/logger'
-require 'capistrano/scm/subversion'
-require 'capistrano/extensions'
+
+require 'capistrano/configuration/callbacks'
+require 'capistrano/configuration/connections'
+require 'capistrano/configuration/execution'
+require 'capistrano/configuration/loading'
+require 'capistrano/configuration/namespaces'
+require 'capistrano/configuration/roles'
+require 'capistrano/configuration/servers'
+require 'capistrano/configuration/variables'
+
+require 'capistrano/configuration/actions/file_transfer'
+require 'capistrano/configuration/actions/inspect'
+require 'capistrano/configuration/actions/invocation'
 
 module Capistrano
   # Represents a specific Capistrano configuration. A Configuration instance
   # may be used to load multiple recipe files, define and describe tasks,
-  # define roles, create an actor, and set configuration variables.
+  # define roles, and set configuration variables.
   class Configuration
-    Role = Struct.new(:host, :options)
-
-    DEFAULT_VERSION_DIR_NAME = "releases" #:nodoc:
-    DEFAULT_CURRENT_DIR_NAME = "current"  #:nodoc:
-    DEFAULT_SHARED_DIR_NAME  = "shared"   #:nodoc:
-
-    # The actor created for this configuration instance.
-    attr_reader :actor
-
-    # The list of Role instances defined for this configuration.
-    attr_reader :roles
-
     # The logger instance defined for this configuration.
-    attr_reader :logger
+    attr_accessor :logger
 
-    # The load paths used for locating recipe files.
-    attr_reader :load_paths
-
-    # The time (in UTC) at which this configuration was created, used for
-    # determining the release path.
-    attr_reader :now
-
-    # The has of variables currently known by the configuration
-    attr_reader :variables
-
-    def initialize(actor_class=Actor) #:nodoc:
-      @roles = Hash.new { |h,k| h[k] = [] }
-      @actor = actor_class.new(self)
+    def initialize #:nodoc:
       @logger = Logger.new
-      @load_paths = [".", File.join(File.dirname(__FILE__), "recipes")]
-      @variables = {}
-      @now = Time.now.utc
-
-      # for preserving the original value of Proc-valued variables
-      set :original_value, Hash.new
-
-      set :application, nil
-      set :repository,  nil
-      set :gateway,     nil
-      set :user,        nil
-      set :password,    nil
-      
-      set :ssh_options, Hash.new
-						
-      set(:deploy_to)   { "/u/apps/#{application}" }
-
-      set :version_dir, DEFAULT_VERSION_DIR_NAME
-      set :current_dir, DEFAULT_CURRENT_DIR_NAME
-      set :shared_dir,  DEFAULT_SHARED_DIR_NAME
-      set :scm,         :subversion
-
-      set(:revision)    { source.latest_revision }
-    end
-
-    # Set a variable to the given value.
-    def set(variable, value=nil, &block)
-      # if the variable is uppercase, then we add it as a constant to the
-      # actor. This is to allow uppercase "variables" to be set and referenced
-      # in recipes.
-      if variable.to_s[0].between?(?A, ?Z)
-        warn "[DEPRECATION] You setting an upper-cased variable, `#{variable}'. Variables should start with a lower-case letter. Support for upper-cased variables will be removed in version 2."
-        klass = @actor.metaclass
-        klass.send(:remove_const, variable) if klass.const_defined?(variable)
-        klass.const_set(variable, value)
-      end
-
-      value = block if value.nil? && block_given?
-      @variables[variable] = value
-    end
-
-    alias :[]= :set
-
-    # Access a named variable. If the value of the variable responds_to? :call,
-    # #call will be invoked (without parameters) and the return value cached
-    # and returned.
-    def [](variable)
-      if @variables[variable].respond_to?(:call)
-        self[:original_value][variable] = @variables[variable]
-        set variable, @variables[variable].call
-      end
-      @variables[variable]
-    end
-
-    # Based on the current value of the <tt>:scm</tt> variable, instantiate and
-    # return an SCM module representing the desired source control behavior.
-    def source
-      @source ||= case scm
-        when Class then
-          scm.new(self)
-        when String, Symbol then
-          require "capistrano/scm/#{scm.to_s.downcase}"
-          Capistrano::SCM.const_get(scm.to_s.downcase.capitalize).new(self)
-        else
-          raise "invalid scm specification: #{scm.inspect}"
-      end
-    end
-
-    # Load a configuration file or string into this configuration.
-    #
-    # Usage:
-    #
-    #   load("recipe"):
-    #     Look for and load the contents of 'recipe.rb' into this
-    #     configuration.
-    #
-    #   load(:file => "recipe"):
-    #     same as above
-    #
-    #   load(:string => "set :scm, :subversion"):
-    #     Load the given string as a configuration specification.
-    #
-    #   load { ... }
-    #     Load the block in the context of the configuration.
-    def load(*args, &block)
-      options = args.last.is_a?(Hash) ? args.pop : {}
-      args.each { |arg| load options.merge(:file => arg) }
-      return unless args.empty?
-
-      if block
-        raise "loading a block requires 0 parameters" unless args.empty?
-        load(options.merge(:proc => block))
-
-      elsif options[:file]
-        file = options[:file]
-        unless file[0] == ?/
-          load_paths.each do |path|
-            if File.file?(File.join(path, file))
-              file = File.join(path, file)
-              break
-            elsif File.file?(File.join(path, file) + ".rb")
-              file = File.join(path, file + ".rb")
-              break
-            end
-          end
-        end
-
-        load :string => File.read(file), :name => options[:name] || file
-
-      elsif options[:string]
-        instance_eval(options[:string], options[:name] || "<eval>")
-
-      elsif options[:proc]
-        instance_eval(&options[:proc])
-
-      else
-        raise ArgumentError, "don't know how to load #{options.inspect}"
-      end
     end
 
-    # Define a new role and its associated servers. You must specify at least
-    # one host for each role. Also, you can specify additional information
-    # (in the form of a Hash) which can be used to more uniquely specify the
-    # subset of servers specified by this specific role definition.
-    #
-    # Usage:
-    #
-    #   role :db, "db1.example.com", "db2.example.com"
-    #   role :db, "master.example.com", :primary => true
-    #   role :app, "app1.example.com", "app2.example.com"
-    def role(which, *args)
-      options = args.last.is_a?(Hash) ? args.pop : {}
-      raise ArgumentError, "must give at least one host" if args.empty?
-      args.each { |host| roles[which] << Role.new(host, options) }
-    end
-
-    # Describe the next task to be defined. The given text will be attached to
-    # the next task that is defined and used as its description.
-    def desc(text)
-      @next_description = text
-    end
+    # make the DSL easier to read when using lazy evaluation via lambdas
+    alias defer lambda
 
-    # Define a new task. If a description is active (see #desc), it is added to
-    # the options under the <tt>:desc</tt> key. This method ultimately
-    # delegates to Actor#define_task.
-    def task(name, options={}, &block)
-      raise ArgumentError, "expected a block" unless block
+    # 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
 
-      if @next_description
-        options = options.merge(:desc => @next_description)
-        @next_description = nil
-      end
+    # Mix in the actions
+    include Actions::FileTransfer, Actions::Inspect, Actions::Invocation
 
-      actor.define_task(name, options, &block)
-    end
-
-    # Require another file. This is identical to the standard require method,
-    # with the exception that it sets the reciever as the "current" configuration
-    # so that third-party task bundles can include themselves relative to
-    # that configuration.
-    def require(*args) #:nodoc:
-      original, Capistrano.configuration = Capistrano.configuration, self
-      super
-    ensure
-      # restore the original, so that require's can be nested
-      Capistrano.configuration = original
-    end
-
-    # Return the path into which releases should be deployed.
-    def releases_path
-      File.join(deploy_to, version_dir)
-    end
-
-    # Return the path identifying the +current+ symlink, used to identify the
-    # current release.
-    def current_path
-      File.join(deploy_to, current_dir)
-    end
-    
-    # Return the path into which shared files should be stored.
-    def shared_path
-      File.join(deploy_to, shared_dir)
-    end
-
-    # Return the full path to the named release. If a release is not specified,
-    # +now+ is used (the time at which the configuration was created).
-    def release_path(release=now.strftime("%Y%m%d%H%M%S"))
-      File.join(releases_path, release)
-    end
-
-    def respond_to?(sym) #:nodoc:
-      @variables.has_key?(sym) || super
-    end
-
-    def method_missing(sym, *args, &block) #:nodoc:
-      if args.length == 0 && block.nil? && @variables.has_key?(sym)
-        self[sym]
-      else
-        super
-      end
-    end
+    # Must mix last, because it hooks into previously defined methods
+    include Callbacks
   end
 end