Module: Kitchen::ShellOut

Overview

Mixin that wraps a command shell out invocation, providing a #run_command method.

Author:

Defined Under Namespace

Classes: ShellCommandFailed

Instance Method Summary collapse

Instance Method Details

#run_command(cmd, options = {}) ⇒ String

Executes a command in a subshell on the local running system.

Parameters:

  • cmd (String)

    command to be executed locally

  • options (Hash) (defaults to: {})

    additional configuration of command

Options Hash (options):

  • :use_sudo (TrueClass, FalseClass)

    whether or not to use sudo

  • :sudo_command (String)

    custom sudo command to use. Default is “sudo -E”.

  • :log_subject (String)

    used in the output or log header for clarity and context. Default is “local”.

  • :cwd (String)

    the directory to chdir to before running the command

  • :environment (Hash)

    a Hash of environment variables to set before the command is run. By default, the environment will always be set to `'LC_ALL' => 'C'` to prevent issues with multibyte characters in Ruby 1.8. To avoid this, use :environment => nil for no extra environment settings, or `:environment => …` to set other environment settings without changing the locale.

  • :timeout (Integer)

    Numeric value for the number of seconds to wait on the child process before raising an Exception. This is calculated as the total amount of time that ShellOut waited on the child process without receiving any output (i.e., IO.select returned nil). Default is 60000 seconds. Note: the stdlib Timeout library is not used.

Returns:

  • (String)

    the standard output of the command as a String

Raises:


57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
# File 'lib/kitchen/shell_out.rb', line 57

def run_command(cmd, options = {})
  if options.fetch(:use_sudo, false)
    cmd = "#{options.fetch(:sudo_command, "sudo -E")} #{cmd}"
  end
  subject = "[#{options.fetch(:log_subject, "local")} command]"

  debug("#{subject} BEGIN (#{cmd})")
  sh = Mixlib::ShellOut.new(cmd, shell_opts(options))
  sh.run_command
  debug("#{subject} END #{Util.duration(sh.execution_time)}")
  sh.error!
  sh.stdout
rescue Mixlib::ShellOut::ShellCommandFailed => ex
  raise ShellCommandFailed, ex.message
rescue Exception => error # rubocop:disable Lint/RescueException
  error.extend(Kitchen::Error)
  raise
end