Debugging

Debugging

RubyShell provides debug mode for detailed command execution logging.

Enabling Debug Mode

Per Block

Enable debug mode for a specific block of commands:

sh(debug: true) do
  mkdir("test")
  cd("test") do
    touch("file.txt")
  end
end

Per Command

Enable debug mode for a single command using the _debug option:

sh.echo("hello", _debug: true)

Globally

Enable debug mode for all commands:

RubyShell.debug = true

sh.echo("hello")  # Will output debug info
sh.ls             # Will output debug info

RubyShell.debug = false  # Disable when done

Debug Output

When debug mode is enabled, each command logs:

Executed: echo hello
  Duration: 0.000312s
  Pid: 12345
  Exit code: 0
  Stdout: "hello"

Field	Description
Executed	The shell command that was run
Duration	Execution time in seconds
Pid	Process ID of the command
Exit code	Exit status (0 = success)
Stdout	The command output

Custom Logger

By default, debug output goes to $stdout. You can configure a custom logger:

# Use a file logger
RubyShell.logger = Logger.new("rubyshell.log")

# Set log level
RubyShell.log_level = :debug  # :debug, :info, :warn, :error

Debugging Pipelines

Debug mode works with command chains too:

sh(debug: true) do
  chain { cat("file.txt") | grep("error") | wc("-l") }
end

Each command in the pipeline will be logged individually.

---

Next: Snippets