Module: Capistrano::Configuration::Actions::Invocation

Module | Capistrano::Configuration::Actions::Invocation
In: | lib/capistrano/configuration/actions/invocation.rb lib/capistrano/configuration/actions/invocation.rb

### Methods

add_default_command_options add_default_command_options continue_execution continue_execution continue_execution_for_branch continue_execution_for_branch invoke_command invoke_command parallel parallel run run sudo sudo sudo_prompt sudo_prompt

### Classes and Modules

Module Capistrano::Configuration::Actions::Invocation::ClassMethods

### Public Instance methods

add_default_command_options(options)

Merges the various default command options into the options hash and returns the result. The default command options that are understand are:

- :default_environment: If the :env key already exists, the :env key is merged into default_environment and then added back into options.
- :default_shell: if the :shell key already exists, it will be used. Otherwise, if the :default_shell key exists in the configuration, it will be used. Otherwise, no :shell key is added.

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 252
    252:         def add_default_command_options(options)
    253:           defaults = self[:default_run_options]
    254:           options = defaults.merge(options)
    255:
    256:           env = self[:default_environment]
    257:           env = env.merge(options[:env]) if options[:env]
    258:           options[:env] = env unless env.empty?
    259:
    260:           shell = options[:shell] || self[:default_shell]
    261:           options[:shell] = shell unless shell.nil?
    262:
    263:           options
    264:         end

add_default_command_options(options)

Merges the various default command options into the options hash and returns the result. The default command options that are understand are:

- :default_environment: If the :env key already exists, the :env key is merged into default_environment and then added back into options.
- :default_shell: if the :shell key already exists, it will be used. Otherwise, if the :default_shell key exists in the configuration, it will be used. Otherwise, no :shell key is added.

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 252
    252:         def add_default_command_options(options)
    253:           defaults = self[:default_run_options]
    254:           options = defaults.merge(options)
    255:
    256:           env = self[:default_environment]
    257:           env = env.merge(options[:env]) if options[:env]
    258:           options[:env] = env unless env.empty?
    259:
    260:           shell = options[:shell] || self[:default_shell]
    261:           options[:shell] = shell unless shell.nil?
    262:
    263:           options
    264:         end

continue_execution(tree)

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 271
    271:         def continue_execution(tree)
    272:           if tree.branches.length == 1
    273:             continue_execution_for_branch(tree.branches.first)
    274:           else
    275:             tree.each { |branch| branch.skip! unless continue_execution_for_branch(branch) }
    276:             tree.any? { |branch| !branch.skip? }
    277:           end
    278:         end

continue_execution(tree)

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 271
    271:         def continue_execution(tree)
    272:           if tree.branches.length == 1
    273:             continue_execution_for_branch(tree.branches.first)
    274:           else
    275:             tree.each { |branch| branch.skip! unless continue_execution_for_branch(branch) }
    276:             tree.any? { |branch| !branch.skip? }
    277:           end
    278:         end

continue_execution_for_branch(branch)

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 280
    280:         def continue_execution_for_branch(branch)
    281:           case Capistrano::CLI.debug_prompt(branch)
    282:             when "y"
    283:               true
    284:             when "n"
    285:               false
    286:             when "a"
    287:               exit(-1)
    288:           end
    289:         end

continue_execution_for_branch(branch)

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 280
    280:         def continue_execution_for_branch(branch)
    281:           case Capistrano::CLI.debug_prompt(branch)
    282:             when "y"
    283:               true
    284:             when "n"
    285:               false
    286:             when "a"
    287:               exit(-1)
    288:           end
    289:         end

invoke_command(cmd, options={}, &block)

Invokes the given command. If a `via` key is given, it will be used to determine what method to use to invoke the command. It defaults to :run, but may be :sudo, or any other method that conforms to the same interface as run and sudo.

[Source]

        # File lib/capistrano/configuration/actions/invocation.rb, line 86
    86:         def invoke_command(cmd, options={}, &block)
    87:           options = options.dup
    88:           via = options.delete(:via) || :run
    89:           send(via, cmd, options, &block)
    90:         end

invoke_command(cmd, options={}, &block)

Invokes the given command. If a `via` key is given, it will be used to determine what method to use to invoke the command. It defaults to :run, but may be :sudo, or any other method that conforms to the same interface as run and sudo.

[Source]

        # File lib/capistrano/configuration/actions/invocation.rb, line 86
    86:         def invoke_command(cmd, options={}, &block)
    87:           options = options.dup
    88:           via = options.delete(:via) || :run
    89:           send(via, cmd, options, &block)
    90:         end

parallel(options={}) {|t| ...}

Executes different commands in parallel. This is useful for commands that need to be different on different hosts, but which could be otherwise run in parallel.

The `options` parameter is currently unused.

Example:

      task :restart_everything do
        parallel do |session|
          session.when "in?(:app)", "/path/to/restart/mongrel"
          session.when "in?(:web)", "/path/to/restart/apache"
          session.when "in?(:db)", "/path/to/restart/mysql"
        end
      end

Each command may have its own callback block, for capturing and responding to output, with semantics identical to run:

      session.when "in?(:app)", "/path/to/restart/mongrel" do |ch, stream, data|
        # ch is the SSH channel for this command, used to send data
        #    back to the command (e.g. ch.send_data("password\n"))
        # stream is either :out or :err, for which stream the data arrived on
        # data is a string containing data sent from the remote command
      end

Also, you can specify a fallback command, to use when none of the conditions match a server:

      session.else "/execute/something/else"

The string specified as the first argument to `when` may be any valid Ruby code. It has access to the following variables and methods:

- +in?(role)+ returns true if the server participates in the given role
- `server` is the ServerDefinition object for the server. This can be used to get the host-name, etc.
- `configuration` is the current Capistrano::Configuration object, which you can use to get the value of variables, etc.

For example:

      session.when "server.host =~ /app/", "/some/command"
      session.when "server.host == configuration[:some_var]", "/another/command"
      session.when "in?(:web) || in?(:app)", "/more/commands"

See run for a description of the valid `options`.

[Source]

        # File lib/capistrano/configuration/actions/invocation.rb, line 76
    76:         def parallel(options={})
    77:           raise ArgumentError, "parallel() requires a block" unless block_given?
    78:           tree = Command::Tree.new(self) { |t| yield t }
    79:           run_tree(tree, options)
    80:         end

parallel(options={}) {|t| ...}

Executes different commands in parallel. This is useful for commands that need to be different on different hosts, but which could be otherwise run in parallel.

The `options` parameter is currently unused.

Example:

      task :restart_everything do
        parallel do |session|
          session.when "in?(:app)", "/path/to/restart/mongrel"
          session.when "in?(:web)", "/path/to/restart/apache"
          session.when "in?(:db)", "/path/to/restart/mysql"
        end
      end

Each command may have its own callback block, for capturing and responding to output, with semantics identical to run:

      session.when "in?(:app)", "/path/to/restart/mongrel" do |ch, stream, data|
        # ch is the SSH channel for this command, used to send data
        #    back to the command (e.g. ch.send_data("password\n"))
        # stream is either :out or :err, for which stream the data arrived on
        # data is a string containing data sent from the remote command
      end

Also, you can specify a fallback command, to use when none of the conditions match a server:

      session.else "/execute/something/else"

The string specified as the first argument to `when` may be any valid Ruby code. It has access to the following variables and methods:

- +in?(role)+ returns true if the server participates in the given role
- `server` is the ServerDefinition object for the server. This can be used to get the host-name, etc.
- `configuration` is the current Capistrano::Configuration object, which you can use to get the value of variables, etc.

For example:

      session.when "server.host =~ /app/", "/some/command"
      session.when "server.host == configuration[:some_var]", "/another/command"
      session.when "in?(:web) || in?(:app)", "/more/commands"

See run for a description of the valid `options`.

[Source]

        # File lib/capistrano/configuration/actions/invocation.rb, line 76
    76:         def parallel(options={})
    77:           raise ArgumentError, "parallel() requires a block" unless block_given?
    78:           tree = Command::Tree.new(self) { |t| yield t }
    79:           run_tree(tree, options)
    80:         end

run(cmd, options={}, &block)

Execute the given command on all servers that are the target of the current task. If a block is given, it is invoked for all output generated by the command, and should accept three parameters: the SSH channel (which may be used to send data back to the remote process), the stream identifier (`:err` for stderr, and `:out` for stdout), and the data that was received.

The `options` hash may include any of the following keys:

- :hosts - this is either a string (for a single target host) or an array of strings, indicating which hosts the command should run on. By default, the hosts are determined from the task definition.
- :roles - this is either a string or symbol (for a single target role) or an array of strings or symbols, indicating which roles the command should run on. If :hosts is specified, :roles will be ignored.
- :only - specifies a condition limiting which hosts will be selected to run the command. This should refer to values set in the role definition. For example, if a role is defined with :primary => true, then you could select only hosts with :primary true by setting :only => { :primary => true }.
- :except - specifies a condition limiting which hosts will be selected to run the command. This is the inverse of :only (hosts that do not match the condition will be selected).
- :once - if true, only the first matching server will be selected. The default is false (all matching servers will be selected).
- :max_hosts - specifies the maximum number of hosts that should be selected at a time. If this value is less than the number of hosts that are selected to run, then the hosts will be run in groups of max_hosts. The default is nil, which indicates that there is no maximum host limit.
- :shell - says which shell should be used to invoke commands. This defaults to "sh". Setting this to false causes Capistrano to invoke the commands directly, without wrapping them in a shell invocation.
- :data - if not nil (the default), this should be a string that will be passed to the command‘s stdin stream.
- :pty - if true, a pseudo-tty will be allocated for each command. The default is false. Note that there are benefits and drawbacks both ways. Empirically, it appears that if a pty is allocated, the SSH server daemon will not read user shell start-up scripts (e.g. bashrc, etc.). However, if a pty is not allocated, some commands will refuse to run in interactive mode and will not prompt for (e.g.) passwords.
- :env - a hash of environment variable mappings that should be made available to the command. The keys should be environment variable names, and the values should be their corresponding values. The default is empty, but may be modified by changing the `default_environment` Capistrano variable.

Note that if you set these keys in the `default_run_options` Capistrano variable, they will apply for all invocations of run, invoke_command, and parallel.

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 140
    140:         def run(cmd, options={}, &block)
    141:           block ||= self.class.default_io_proc
    142:           tree = Command::Tree.new(self) { |t| t.else(cmd, &block) }
    143:           run_tree(tree, options)
    144:         end

run(cmd, options={}, &block)

Execute the given command on all servers that are the target of the current task. If a block is given, it is invoked for all output generated by the command, and should accept three parameters: the SSH channel (which may be used to send data back to the remote process), the stream identifier (`:err` for stderr, and `:out` for stdout), and the data that was received.

The `options` hash may include any of the following keys:

- :hosts - this is either a string (for a single target host) or an array of strings, indicating which hosts the command should run on. By default, the hosts are determined from the task definition.
- :roles - this is either a string or symbol (for a single target role) or an array of strings or symbols, indicating which roles the command should run on. If :hosts is specified, :roles will be ignored.
- :only - specifies a condition limiting which hosts will be selected to run the command. This should refer to values set in the role definition. For example, if a role is defined with :primary => true, then you could select only hosts with :primary true by setting :only => { :primary => true }.
- :except - specifies a condition limiting which hosts will be selected to run the command. This is the inverse of :only (hosts that do not match the condition will be selected).
- :once - if true, only the first matching server will be selected. The default is false (all matching servers will be selected).
- :max_hosts - specifies the maximum number of hosts that should be selected at a time. If this value is less than the number of hosts that are selected to run, then the hosts will be run in groups of max_hosts. The default is nil, which indicates that there is no maximum host limit.
- :shell - says which shell should be used to invoke commands. This defaults to "sh". Setting this to false causes Capistrano to invoke the commands directly, without wrapping them in a shell invocation.
- :data - if not nil (the default), this should be a string that will be passed to the command‘s stdin stream.
- :pty - if true, a pseudo-tty will be allocated for each command. The default is false. Note that there are benefits and drawbacks both ways. Empirically, it appears that if a pty is allocated, the SSH server daemon will not read user shell start-up scripts (e.g. bashrc, etc.). However, if a pty is not allocated, some commands will refuse to run in interactive mode and will not prompt for (e.g.) passwords.
- :env - a hash of environment variable mappings that should be made available to the command. The keys should be environment variable names, and the values should be their corresponding values. The default is empty, but may be modified by changing the `default_environment` Capistrano variable.

Note that if you set these keys in the `default_run_options` Capistrano variable, they will apply for all invocations of run, invoke_command, and parallel.

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 140
    140:         def run(cmd, options={}, &block)
    141:           block ||= self.class.default_io_proc
    142:           tree = Command::Tree.new(self) { |t| t.else(cmd, &block) }
    143:           run_tree(tree, options)
    144:         end

sudo(*parameters, &block)

Returns the command string used by capistrano to invoke a comamnd via sudo.

      run "#{sudo :as => 'bob'} mkdir /path/to/dir"

It can also be invoked like run, but executing the command via sudo. This assumes that the sudo password (if required) is the same as the password for logging in to the server.

      sudo "mkdir /path/to/dir"

Also, this method understands a `:sudo` configuration variable, which (if specified) will be used as the full path to the sudo executable on the remote machine:

      set :sudo, "/opt/local/bin/sudo"

If you know what you‘re doing, you can also set `:sudo_prompt`, which tells capistrano which prompt sudo should use when asking for a password. (This is so that capistrano knows what prompt to look for in the output.) If you set :sudo_prompt to an empty string, Capistrano will not send a preferred prompt.

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 199
    199:         def sudo(*parameters, &block)
    200:           options = parameters.last.is_a?(Hash) ? parameters.pop.dup : {}
    201:           command = parameters.first
    202:           user = options[:as] && "-u #{options.delete(:as)}"
    203:
    204:           sudo_prompt_option = "-p '#{sudo_prompt}'" unless sudo_prompt.empty?
    205:           sudo_command = [fetch(:sudo, "sudo"), sudo_prompt_option, user].compact.join(" ")
    206:
    207:           if command
    208:             command = sudo_command + " " + command
    209:             run(command, options, &block)
    210:           else
    211:             return sudo_command
    212:           end
    213:         end

sudo(*parameters, &block)

Returns the command string used by capistrano to invoke a comamnd via sudo.

      run "#{sudo :as => 'bob'} mkdir /path/to/dir"

It can also be invoked like run, but executing the command via sudo. This assumes that the sudo password (if required) is the same as the password for logging in to the server.

      sudo "mkdir /path/to/dir"

Also, this method understands a `:sudo` configuration variable, which (if specified) will be used as the full path to the sudo executable on the remote machine:

      set :sudo, "/opt/local/bin/sudo"

If you know what you‘re doing, you can also set `:sudo_prompt`, which tells capistrano which prompt sudo should use when asking for a password. (This is so that capistrano knows what prompt to look for in the output.) If you set :sudo_prompt to an empty string, Capistrano will not send a preferred prompt.

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 199
    199:         def sudo(*parameters, &block)
    200:           options = parameters.last.is_a?(Hash) ? parameters.pop.dup : {}
    201:           command = parameters.first
    202:           user = options[:as] && "-u #{options.delete(:as)}"
    203:
    204:           sudo_prompt_option = "-p '#{sudo_prompt}'" unless sudo_prompt.empty?
    205:           sudo_command = [fetch(:sudo, "sudo"), sudo_prompt_option, user].compact.join(" ")
    206:
    207:           if command
    208:             command = sudo_command + " " + command
    209:             run(command, options, &block)
    210:           else
    211:             return sudo_command
    212:           end
    213:         end

sudo_prompt()

Returns the prompt text to use with sudo

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 267
    267:         def sudo_prompt
    268:           fetch(:sudo_prompt, "sudo password: ")
    269:         end

sudo_prompt()

Returns the prompt text to use with sudo

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 267
    267:         def sudo_prompt
    268:           fetch(:sudo_prompt, "sudo password: ")
    269:         end

[Validate]