Airbrussh

Airbrussh is a concise log formatter for Capistrano and SSHKit. It displays well-formatted, useful log output that is easy to read. Airbrussh also saves Capistrano's verbose output to a separate log file just in case you need additional details for troubleshooting.

As of April 2016, Airbrussh is bundled with Capistrano 3.5, and is Capistrano's default formatter! There is nothing additional to install or enable. Continue reading to learn more about Airbrussh's features and configuration options.

If you aren't yet using Capistrano 3.5 (or wish to use Airbrussh with SSHKit directly), refer to the advanced/legacy usage section for installation instructions.

Sample output

For more details on how exactly Airbrussh affects Capistrano's output and the reasoning behind it, check out the blog post: Introducing Airbrussh.

Usage
Configuration
FAQ
Advanced/legacy usage

Usage

Airbrussh is enabled by default in Capistrano 3.5 and newer. To manually enable Airbrussh (for example, when upgrading an existing project), set the Capistrano format like this:

# In deploy.rb
set :format, :airbrussh

What's displayed

When you run a Capistrano command, Airbrussh provides the following information in its output:

Sample output

Name of Capistrano task being executed
When each task started (minutes:seconds elapsed since the deploy began)
The SSH command-line strings that are executed; for Capistrano tasks that involve running multiple commands, the numeric prefix indicates the command in the sequence, starting from 01
Stdout and stderr output from each command
The duration of each command execution, per server

What's not displayed

For brevity, Airbrussh does not show everything that Capistrano is doing. For example, it will omit Capistrano's test commands, which can be noisy and confusing. Airbrussh also hides things like environment variables, as well as cd and env invocations. To see a full audit of Capistrano's execution, including exactly what commands were run on each server, look at log/capistrano.log.

Configuration

You can customize many aspects of Airbrussh's output. In Capistrano 3.5 and newer, this is done via the :format_options variable, like this:

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

Here are the options you can use, and their effects (note that the defaults may be different depending on where Airbrussh is used; these are the defaults used by Capistrano 3.5):

Option	Default	Usage
`banner`	`nil`	Provide a string (e.g. "Capistrano started!") that will be printed when Capistrano starts up.
`color`	`:auto`	Use `true` or `false` to enable or disable ansi color. If set to `:auto`, Airbrussh automatically uses color based on whether the output is a TTY, or if the SSHKIT_COLOR environment variable is set.
`command_output`	`true`	Set to `:stdout`, `:stderr`, or `true` to display the SSH output received via stdout, stderr, or both, respectively. Set to `false` to not show any SSH output, for a minimal look.
`context`	`Airbrussh::Rake::Context`	Defines the execution context. Targeted towards uses of Airbrussh outside of Rake/Capistrano. Alternate implementations should provide the definition for `current_task_name`, `register_new_command`, and `position`.
`log_file`	`log/capistrano.log`	Capistrano's verbose output is saved to this file to facilitate debugging. Set to `nil` to disable completely.
`truncate`	`:auto`	Set to a number (e.g. 80) to truncate the width of the output to that many characters, or `false` to disable truncation. If `:auto`, output is automatically truncated to the width of the terminal window, if it can be determined.
`task_prefix`	`nil`	A string to prefix to task output. Handy for output collapsing like buildkite's `---` prefix

FAQ

Airbrussh is not displaying the output of my commands! For example, I run tail in one of my capistrano tasks and airbrussh doesn't show anything. How do I fix this?

Make sure Airbrussh is configured to show SSH output.

set :format_options, command_output: true

I haven't upgraded to Capistrano 3.5 yet. Can I still use Airbrussh?

Yes! Capistrano 3.4.x is also supported. Refer to the advanced/legacy usage section for installation instructions.

Does Airbrussh work with Capistrano 2?

No, Capistrano 3 is required. We recommend Capistrano 3.4.0 or higher. Capistrano 3.5.0 and higher have Airbrussh enabled by default, with no installation needed.

Does Airbrussh work with JRuby?

JRuby is not officially supported or tested, but may work. You must disable automatic truncation to work around a known bug in the JRuby 9.0 standard library. See #62 for more details.

set :format_options, truncate: false

I have a question that’s not answered here or elsewhere in the README.

Please open a GitHub issue and we’ll be happy to help!

Advanced/legacy usage

Although Airbrussh is built into Capistrano 3.5.0 and higher, it is also available as a plug-in for older versions. Airbrussh has been tested with MRI 1.9+, Capistrano 3.4.0+, and SSHKit 1.6.1+.

Capistrano 3.4.x

Add this line to your application's Gemfile:

gem "airbrussh", require: false

And then execute:

$ bundle

Finally, add this line to your application's Capfile:

require "airbrussh/capistrano"

Important: explicitly setting Capistrano's :format option in your deploy.rb will override airbrussh. Remove this line if you have it:

# Remove this
set :format, :pretty

Capistrano 3.4.x doesn't have the :format_options configuration system, so you will need to configure Airbrussh using this technique:

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

Refer to the configuration section above for the list of supported options.

SSHKit

If you are using SSHKit directly (i.e. without Capistrano), you can use Airbrussh like this:

require "airbrussh"
SSHKit.config.output = Airbrussh::Formatter.new($stdout)

# You can also pass configuration options like this
SSHKit.config.output = Airbrussh::Formatter.new($stdout, color: false)

History

Airbrussh started life as custom logging code within the capistrano-mb collection of opinionated Capistrano recipes. In February 2015, the logging code was refactored into a standalone gem with its own configuration and documentation, and renamed airbrussh. In February 2016, Airbrussh was added as the default formatter in Capistrano 3.5.0.

Roadmap

Airbrussh now has a stable feature set, excellent test coverage, is being used for production deployments, and has reached 1.0.0! If you have ideas for improvements to Airbrussh, please open a GitHub issue.

Contributing

Contributions are welcome! Read CONTRIBUTING.md to get started.