Module | Capistrano::Configuration::Actions::Invocation |
In: |
lib/capistrano/configuration/actions/invocation.rb
lib/capistrano/configuration/actions/invocation.rb |
Merges the various default command options into the options hash and returns the result. The default command options that are understand are:
# 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
Merges the various default command options into the options hash and returns the result. The default command options that are understand are:
# 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
# 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
# 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
# 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
# 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
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.
# 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
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.
# 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
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:
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.
# 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
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:
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.
# 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
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:
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.
# 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
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:
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.
# 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
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.
# 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
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.
# 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