Airbrussh

Airbrussh is the default formatter in Capistrano 3.5 and newer. If you are using Capistrano 3.5+ and want to ensure it is active, or if you are upgrading an existing project, you can manually enable it in your deploy.rb file.

Note: If you are on Capistrano 3.4.x, you must follow the Advanced/legacy usage instructions to install it as a plugin.

```ruby
# In deploy.rb
set :format, :airbrussh
```埋

In Capistrano 3.5 and newer, you can customize Airbrussh's output by setting the :format_options variable in your deploy.rb. This allows you to control colors, output verbosity, truncation, and more.

Example of setting multiple options:

set :format_options, color: false, truncate: 80

# Pass options to Airbrussh
set :format_options, color: false, truncate: 80

Capistrano 3.4.x does not support the :format_options configuration system. Instead, you must use the Airbrussh.configure block in your configuration files.

Airbrussh.configure do |config|
  config.color = false
  config.command_output = true
  # etc.
end

When upgrading to Capistrano 3.5.0 or later, Airbrussh is built into Capistrano and enabled by default. You must perform the following cleanup steps to avoid conflicts:

1. Gemfile: Remove gem "airbrussh" (it is now included automatically by Capistrano).
2. Capfile: Remove require "capistrano/airbrussh" (Capistrano now handles this internally).
3. deploy.rb: Replace the Airbrussh.configure block with the new set :format_options configuration method.

# 1. Remove from Gemfile
# gem "airbrussh"

# 2. Remove from Capfile
# require "capistrano/airbrussh"

If you are using Capistrano 3.4.x, Airbrussh is not bundled and must be installed as a plugin.

1. Add the gem to your Gemfile:

gem "airbrussh", require: false

2. Run bundle.
3. Add the requirement to your Capfile:

require "airbrussh/capistrano"

Warning: Ensure you do not have set :format, :pretty in your deploy.rb, as this will override Airbrussh.

# Gemfile
gem "airbrussh", require: false

# Capfile
require "airbrussh/capistrano"

# deploy.rb (Ensure this is NOT present)
# set :format, :pretty

Capistrano 3.5.0 introduced new default behaviors that may make output more verbose than previous versions. Specifically, banner is now false and command_output is now true.

To restore the output behavior used in versions prior to Capistrano 3.5.0, use the following configuration in your deploy.rb:

set :format_options, banner: :auto, command_output: false

Airbrussh's Console class manages how log messages are written to an IO object (like STDOUT). It handles automatic line truncation to fit the console width and manages ANSI color stripping based on whether the output is a TTY or a CI environment.

Truncation Behavior

Controlled via config.truncate. Supported values:

• :auto: Automatically detects the console width using IO.console.winsize.last if the output is a TTY.
• Integer: Sets a fixed character width for truncation.

Color Behavior

Controlled via config.color. Supported values:

• true: Always enables ANSI color output.
• :auto: Enables color if the output is a TTY OR if the SSHKIT_COLOR environment variable is set.
• false: Always disables color (strips ANSI codes).

If truncation occurs, Airbrussh appends an ellipsis (… if UTF-8 is supported, otherwise ...) and resets the color sequence.

The command_output configuration option determines which command outputs are displayed.

• If set to false (default), no command output is shown.
• If set to true, all command output is shown.
• If set to an Array of symbols (e.g., [:rake, :deploy]), only the output for those specific commands will be shown.

Use the show_command_output?(sym) method to check if a specific command's output should be displayed.

# Configuration for specific commands
config.command_output = [:rake, :deploy]

# Checking visibility for a command
config.show_command_output?(:rake)    # => true
config.show_command_output?(:deploy)  # => true
config.show_command_output?(:other)   # => false

The Airbrussh::Rake::Context class maintains information about the currently executing Rake task. It works by monkey patching Rake::Task#execute to update the current_task_name.

Thread Safety Warning

Airbrussh::Rake::Context is not thread-safe. In Capistrano environments where invoke is used to switch Rake tasks in the middle of an SSHKit thread, the context may become unreliable and position(command) may return nil.

In Capistrano 3.5.0 and later, Airbrussh is configured by assigning a Hash to the :format_options variable using Capistrano's set method. The configuration keys remain the same as the previous version, but the syntax has changed from a configuration block to a Hash assignment.

# New syntax for Capistrano 3.5+
set :format_options, color: false

To use Airbrussh's specialized Capistrano integration, you must ensure the gem is loaded within your application's Capfile. This integration automatically configures Airbrussh to use log/capistrano.log as its log file and enables monkey-patching for Rake to ensure consistent output formatting during deployments.

When a deployment fails, the integration provides a specialized deploy_failed behavior that prints a red error header and tails the last 20 lines of the Capistrano log file to the console for immediate debugging.

# In your Capfile
require 'airbrussh/capistrano'