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 run_tree run_tree 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 152
    152:         def add_default_command_options(options)
    153:           defaults = self[:default_run_options]
    154:           options = defaults.merge(options)
    155:
    156:           env = self[:default_environment]
    157:           env = env.merge(options[:env]) if options[:env]
    158:           options[:env] = env unless env.empty?
    159:
    160:           shell = options[:shell] || self[:default_shell]
    161:           options[:shell] = shell unless shell.nil?
    162:
    163:           options
    164:         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 152
    152:         def add_default_command_options(options)
    153:           defaults = self[:default_run_options]
    154:           options = defaults.merge(options)
    155:
    156:           env = self[:default_environment]
    157:           env = env.merge(options[:env]) if options[:env]
    158:           options[:env] = env unless env.empty?
    159:
    160:           shell = options[:shell] || self[:default_shell]
    161:           options[:shell] = shell unless shell.nil?
    162:
    163:           options
    164:         end

continue_execution(tree)

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 171
    171:         def continue_execution(tree)
    172:           if tree.branches.length == 1
    173:             continue_execution_for_branch(tree.branches.first)
    174:           else
    175:             tree.each { |branch| branch.skip! unless continue_execution_for_branch(branch) }
    176:             tree.any? { |branch| !branch.skip? }
    177:           end
    178:         end

continue_execution(tree)

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 171
    171:         def continue_execution(tree)
    172:           if tree.branches.length == 1
    173:             continue_execution_for_branch(tree.branches.first)
    174:           else
    175:             tree.each { |branch| branch.skip! unless continue_execution_for_branch(branch) }
    176:             tree.any? { |branch| !branch.skip? }
    177:           end
    178:         end

continue_execution_for_branch(branch)

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 180
    180:         def continue_execution_for_branch(branch)
    181:           case Capistrano::CLI.debug_prompt(branch)
    182:             when "y"
    183:               true
    184:             when "n"
    185:               false
    186:             when "a"
    187:               exit(-1)
    188:           end
    189:         end

continue_execution_for_branch(branch)

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 180
    180:         def continue_execution_for_branch(branch)
    181:           case Capistrano::CLI.debug_prompt(branch)
    182:             when "y"
    183:               true
    184:             when "n"
    185:               false
    186:             when "a"
    187:               exit(-1)
    188:           end
    189:         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 39
    39:         def invoke_command(cmd, options={}, &block)
    40:           options = options.dup
    41:           via = options.delete(:via) || :run
    42:           send(via, cmd, options, &block)
    43:         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 39
    39:         def invoke_command(cmd, options={}, &block)
    40:           options = options.dup
    41:           via = options.delete(:via) || :run
    42:           send(via, cmd, options, &block)
    43:         end

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

[Source]

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

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

[Source]

        # File lib/capistrano/configuration/actions/invocation.rb, line 29
    29:         def parallel(options={})
    30:           raise ArgumentError, "parallel() requires a block" unless block_given?
    31:           tree = Command::Tree.new(self) { |t| yield t }
    32:           run_tree(tree)
    33:         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.

[Source]

        # File lib/capistrano/configuration/actions/invocation.rb, line 51
    51:         def run(cmd, options={}, &block)
    52:           block ||= self.class.default_io_proc
    53:           tree = Command::Tree.new(self) { |t| t.else(cmd, &block) }
    54:           run_tree(tree, options)
    55:         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.

[Source]

        # File lib/capistrano/configuration/actions/invocation.rb, line 51
    51:         def run(cmd, options={}, &block)
    52:           block ||= self.class.default_io_proc
    53:           tree = Command::Tree.new(self) { |t| t.else(cmd, &block) }
    54:           run_tree(tree, options)
    55:         end

run_tree(tree, options={})

[Source]

        # File lib/capistrano/configuration/actions/invocation.rb, line 57
    57:         def run_tree(tree, options={})
    58:           if tree.branches.empty? && tree.fallback
    59:             logger.debug "executing #{tree.fallback}"
    60:           elsif tree.branches.any?
    61:             logger.debug "executing multiple commands in parallel"
    62:             tree.each do |branch|
    63:               logger.trace "-> #{branch}"
    64:             end
    65:           else
    66:             raise ArgumentError, "attempt to execute without specifying a command"
    67:           end
    68:
    69:           return if dry_run || (debug && continue_execution(tree) == false)
    70:
    71:           options = add_default_command_options(options)
    72:
    73:           tree.each do |branch|
    74:             if branch.command.include?(sudo)
    75:               branch.callback = sudo_behavior_callback(branch.callback)
    76:             end
    77:           end
    78:
    79:           execute_on_servers(options) do |servers|
    80:             targets = servers.map { |s| sessions[s] }
    81:             Command.process(tree, targets, options.merge(:logger => logger))
    82:           end
    83:         end

run_tree(tree, options={})

[Source]

        # File lib/capistrano/configuration/actions/invocation.rb, line 57
    57:         def run_tree(tree, options={})
    58:           if tree.branches.empty? && tree.fallback
    59:             logger.debug "executing #{tree.fallback}"
    60:           elsif tree.branches.any?
    61:             logger.debug "executing multiple commands in parallel"
    62:             tree.each do |branch|
    63:               logger.trace "-> #{branch}"
    64:             end
    65:           else
    66:             raise ArgumentError, "attempt to execute without specifying a command"
    67:           end
    68:
    69:           return if dry_run || (debug && continue_execution(tree) == false)
    70:
    71:           options = add_default_command_options(options)
    72:
    73:           tree.each do |branch|
    74:             if branch.command.include?(sudo)
    75:               branch.callback = sudo_behavior_callback(branch.callback)
    76:             end
    77:           end
    78:
    79:           execute_on_servers(options) do |servers|
    80:             targets = servers.map { |s| sessions[s] }
    81:             Command.process(tree, targets, options.merge(:logger => logger))
    82:           end
    83:         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"

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 101
    101:         def sudo(*parameters, &block)
    102:           options = parameters.last.is_a?(Hash) ? parameters.pop.dup : {}
    103:           command = parameters.first
    104:           user = options[:as] && "-u #{options.delete(:as)}"
    105:
    106:           sudo_prompt_option = "-p '#{sudo_prompt}'" unless sudo_prompt.empty?
    107:           sudo_command = [fetch(:sudo, "sudo"), sudo_prompt_option, user].compact.join(" ")
    108:
    109:           if command
    110:             command = sudo_command + " " + command
    111:             run(command, options, &block)
    112:           else
    113:             return sudo_command
    114:           end
    115:         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"

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 101
    101:         def sudo(*parameters, &block)
    102:           options = parameters.last.is_a?(Hash) ? parameters.pop.dup : {}
    103:           command = parameters.first
    104:           user = options[:as] && "-u #{options.delete(:as)}"
    105:
    106:           sudo_prompt_option = "-p '#{sudo_prompt}'" unless sudo_prompt.empty?
    107:           sudo_command = [fetch(:sudo, "sudo"), sudo_prompt_option, user].compact.join(" ")
    108:
    109:           if command
    110:             command = sudo_command + " " + command
    111:             run(command, options, &block)
    112:           else
    113:             return sudo_command
    114:           end
    115:         end

sudo_prompt()

Returns the prompt text to use with sudo

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 167
    167:         def sudo_prompt
    168:           fetch(:sudo_prompt, "sudo password: ")
    169:         end

sudo_prompt()

Returns the prompt text to use with sudo

[Source]

         # File lib/capistrano/configuration/actions/invocation.rb, line 167
    167:         def sudo_prompt
    168:           fetch(:sudo_prompt, "sudo password: ")
    169:         end

[Validate]