airbrussh 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6d98e543aa9b5dc67eb5134f92d48dd5a23cb8a2
-  data.tar.gz: 0301592589165f633040120602aff81f5c2a8737
+  metadata.gz: 58dc91f927b5a666da9937a9b2645aeedb63dda0
+  data.tar.gz: c11b7735895deeecf2033856e9ce908850f21031
 SHA512:
-  metadata.gz: 4b371ea1f4048cdc045f5e1b439081bb8e2104451d2f14b0273f9991a7f1a89183d07fff9029adb683acc7a8e903e6acd9557b51c217029c8ad23ea3bef1a474
-  data.tar.gz: 757d92a563681358bf8c2913c8d64454a0e37fb52a617d4a4f1a8e56cae7e6518e06250a8c52e318ee6cddcf3a22bf73dcc1dad69d4e2ab7e96ed60ec04572a4
+  metadata.gz: 91dd2ec74fbf99452f8a81e54dae332add830e11d71b76c536f08a35298e9eb7d1f54724f8705686f35ca29bbf0b90e6a2d382a70954e9420c897b43c706c363
+  data.tar.gz: 0b6938a668435f82acd1b37f5a5f75a63ffffcf8de9577357a02a06b0d03db42059f33c10c7a071e25f7cde5892845286f8519bd878d2801d3afedb33dbd0e48

data/CHANGELOG.md

@@ -6,6 +6,13 @@ All notable changes to this project will be documented in this file. This projec
 
 * Your contribution here!
 
+## [1.0.2][] (2016-05-13)
+
+* Fix a crash that can happen in certain multi-server deployments when
+  Capistrano's `invoke` is used to switch Rake tasks in the middle of SSHKit
+  execution ([#78](https://github.com/mattbrictson/airbrussh/issues/78),
+  [#80](https://github.com/mattbrictson/airbrussh/pull/80))
+
 ## [1.0.1][] (2016-03-21)
 
 * Fix support for fake TTYs reporting a 0 width console like Ruby's PTY library [#76](https://github.com/mattbrictson/airbrussh/pull/76)
@@ -99,7 +106,8 @@ There are, however, many behind-the-scenes changes and improvements to overall c
 * Initial release
 
 [Semver]: http://semver.org
-[Unreleased]: https://github.com/mattbrictson/airbrussh/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/mattbrictson/airbrussh/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/mattbrictson/airbrussh/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/mattbrictson/airbrussh/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/mattbrictson/airbrussh/compare/v1.0.0.beta1...v1.0.0
 [1.0.0.beta1]: https://github.com/mattbrictson/airbrussh/compare/v0.8.0...v1.0.0.beta1

data/README.md

@@ -7,191 +7,157 @@
 [![Coverage Status](https://coveralls.io/repos/mattbrictson/airbrussh/badge.svg?branch=master)](https://coveralls.io/r/mattbrictson/airbrussh?branch=master)
 
 
-**Airbrussh is a replacement log formatter for SSHKit that makes your Capistrano output much easier on the eyes.** Just add it to your Capfile and enjoy concise, useful log output that is easy to read.
+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.
 
-And don't worry: airbrussh saves Capistrano's default verbose output to a separate log file just in case you still need it 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.
 
-![Sample output](https://raw.github.com/mattbrictson/airbrussh/master/demo.gif)
-
-For more details on how exactly Airbrussh changes Capistrano's output and the reasoning behind it, check out the blog post: [Introducing Airbrussh](https://mattbrictson.com/airbrussh).
+If you aren't yet using Capistrano 3.5 (or wish to use Airbrussh with SSHKit directly), refer to the [advanced/legacy usage](#advancedlegacy-usage) section for installation instructions.
 
-## Requirements
+![Sample output](https://raw.github.com/mattbrictson/airbrussh/master/demo.gif)
 
-**To use Airbrussh with Capistrano, you will need Capistrano 3.** Capistrano 2.x is not supported.
+For more details on how exactly Airbrussh affects Capistrano's output and the reasoning behind it, check out the blog post: [Introducing Airbrussh](https://mattbrictson.com/airbrussh).
 
-Airbrussh has been tested with MRI 1.9+, Capistrano 3.4.0, and SSHKit 1.6.1+. Refer to the [Travis configuration](.travis.yml) for our latest test matrix. If you run into trouble using airbrussh in your environment, [open an issue on GitHub](https://github.com/mattbrictson/airbrussh/issues/new).
+-----
 
-Airbrussh's only dependency is SSHKit >= 1.6.1.
+* [Usage](#usage)
+* [Configuration](#configuration)
+* [FAQ](#faq)
+* [Advanced/legacy usage](#advancedlegacy-usage)
 
-## Installation
+## Usage
 
-Add this line to your application's Gemfile:
+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:
 
 ```ruby
-gem "airbrussh", :require => false
+# In deploy.rb
+set :format, :airbrussh
 ```
 
-And then execute:
+### What's displayed
 
-    $ bundle
+When you run a Capistrano command, Airbrussh provides the following information in its output:
 
-Finally, add this line to your application's Capfile:
+![Sample output](https://raw.github.com/mattbrictson/airbrussh/master/formatting.png)
 
-```ruby
-require "airbrussh/capistrano"
-```
+* 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
 
-**Important:** explicitly setting Capistrano's `:format` option in your deploy.rb will override airbrussh. Remove this line if you have it:
+### What's *not* displayed
 
-```ruby
-# Remove this
-set :format, :pretty
-```
+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`.
 
-## Usage
+## Configuration
 
-Airbrussh automatically replaces the default Capistrano log formatter, so there is nothing more you have to do. Just run `cap` as normal and enjoy the prettier output!
+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:
 
-For advanced usage, refer to the these sections below:
+```ruby
+# Pass options to Airbrussh
+set :format_options, color: false, truncate: 80
+```
 
-* [FAQ](#faq)
-* [Advanced configuration](#advanced-configuration)
-* [Usage outside of Capistrano](#usage-outside-of-capistrano)
+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.|
+|`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.|
 
 ## 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?**
 
-For brevity, airbrussh mutes all output (stdout and stderr) of commands by default. To show all output, add this to your `deploy.rb` (see also the other [configuration options](#advanced-configuration) later in this README):
+Make sure Airbrussh is configured to show SSH output.
 
 ```ruby
-Airbrussh.configure do |config|
-  config.command_output = true
-end
+set :format_options, command_output: true
 ```
 
-**Does airbrussh work with Capistrano 2?**
+**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](#advancedlegacy-usage) section for installation instructions.
 
-No, Capistrano 3 is required. We recommend Capistrano 3.4.0 or higher.
+**Does Airbrussh work with Capistrano 2?**
 
-**Does airbrussh work with JRuby?**
+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.
 
-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.1.0 standard library. See [#62](https://github.com/mattbrictson/airbrussh/issues/62) for more details.
+**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](https://github.com/mattbrictson/airbrussh/issues/62) for more details.
 
 ```ruby
-Airbrussh.configure do |config|
-  # Disable automatic truncation for JRuby compatibility
-  config.truncate = false
-end
+set :format_options, truncate: false
 ```
 
 **I have a question that’s not answered here or elsewhere in the README.**
 
 Please [open a GitHub issue](https://github.com/mattbrictson/airbrussh/issues/new) and we’ll be happy to help!
 
-## Advanced configuration
+## Advanced/legacy usage
 
-Airbrussh can be configured by calling `Airbrussh.configure` in your `deploy.rb` file. You can do stage-specific configuration in e.g. `deploy/production.rb` as well. Here are the available options:
+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:
 
 ```ruby
-Airbrussh.configure do |config|
-  # Capistrano's default, un-airbrusshed output is saved to a file to
-  # facilitate debugging.
-  #
-  # To disable this entirely:
-  # config.log_file = nil
-  #
-  # Default:
-  config.log_file = "log/capistrano.log"
-
-  # Airbrussh patches Rake so it can access the name of the currently executing
-  # task. Set this to false if monkey patching is causing issues.
-  #
-  # Default:
-  config.monkey_patch_rake = true
-
-  # Ansi colors will be used in the output automatically based on whether the
-  # output is a TTY, or if the SSHKIT_COLOR environment variable is set.
-  #
-  # To disable color always:
-  # config.color = false
-  #
-  # Default:
-  config.color = :auto
-
-  # Output is automatically truncated to the width of the terminal window, if
-  # possible. If the width of the terminal can't be determined, no truncation
-  # is performed.
-  #
-  # To truncate to a fixed width:
-  # config.truncate = 80
-  #
-  # Or to disable truncation entirely:
-  # config.truncate = false
-  #
-  # Default:
-  config.truncate = :auto
-
-  # If a log_file is configured, airbrussh will output a message at startup
-  # displaying the log_file location.
-  #
-  # To always disable this message:
-  # config.banner = false
-  #
-  # To display an alternative message:
-  # config.banner = "Hello, world!"
-  #
-  # Default:
-  config.banner = :auto
-
-  # You can control whether airbrussh shows the output of SSH commands. For
-  # brevity, the output is hidden by default.
-  #
-  # Display stdout of SSH commands. Stderr is not displayed.
-  # config.command_output = :stdout
-  #
-  # Display stderr of SSH commands. Stdout is not displayed.
-  # config.command_output = :stderr
-  #
-  # Display all SSH command output.
-  # config.command_output = [:stdout, :stderr]
-  # or
-  # config.command_output = true
-  #
-  # Default (all output suppressed):
-  config.command_output = false
-end
+gem "airbrussh", require: false
 ```
 
-## Usage outside of Capistrano
+And then execute:
 
-If you are using SSHKit directly, you can use Airbrussh without the Capistrano magic:
+    $ bundle
+
+Finally, add this line to your application's Capfile:
 
 ```ruby
-require "airbrussh"
-SSHKit.config.output = Airbrussh::Formatter.new($stdout)
+require "airbrussh/capistrano"
 ```
 
-When Capistrano is not present, Airbrussh uses a slightly different default configuration:
+**Important:** explicitly setting Capistrano's `:format` option in your deploy.rb will override airbrussh. Remove this line if you have it:
+
+```ruby
+# 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:
 
 ```ruby
 Airbrussh.configure do |config|
-  config.log_file = nil
-  config.monkey_patch_rake = false
-  config.color = :auto
-  config.truncate = :auto
-  config.banner = :auto
-  config.command_output = false
+  config.color = false
+  config.command_output = true
+  # etc.
 end
 ```
 
+Refer to the [configuration](#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:
+
+```ruby
+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`. Now anyone can using SSHKit or Capistrano can safely plug it into their projects!
+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! Work is [underway](https://github.com/capistrano/capistrano/pull/1541) to integrate Airbrussh with the next Capistrano release. If you have ideas for improvements to Airbrussh, please open a [GitHub issue](https://github.com/mattbrictson/airbrussh/issues/new).
+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](https://github.com/mattbrictson/airbrussh/issues/new).
 
 ## Contributing
 

data/UPGRADING-CAP-3.5.md

@@ -40,7 +40,7 @@ Capistrano 3.5.0 changes Airbrussh defaults as follows:
 Therefore, after upgrading to Capistrano 3.5.0, you may notice Airbrussh's output has changed and become more verbose. To restore the defaults to what you were used to in older versions, do this:
 
 ```ruby
-set :format_options, banner: auto, command_output: false
+set :format_options, banner: :auto, command_output: false
 ```
 
 ## Trouble?

data/lib/airbrussh/capistrano/tasks.rb

@@ -66,7 +66,8 @@ module Airbrussh
           red("WARNING: airbrussh/capistrano must be loaded by Capistrano in "\
               "order to work.\nRequire this gem within your application's "\
               "Capfile, as described here:\n"\
-              "https://github.com/mattbrictson/airbrussh#installation"))
+              "https://github.com/mattbrictson/airbrussh#installation")
+        )
       end
 
       def err_console

data/lib/airbrussh/command_formatter.rb

@@ -8,8 +8,8 @@ module Airbrussh
   # command's position within currently executing rake task:
   #
   # * position - zero-based position of this command in the list of
-  #              all commands that have been run in the current rake task
-  #  class CommandFormatter < SimpleDelegator
+  #              all commands that have been run in the current rake task; in
+  #              some cases this could be nil
   class CommandFormatter < SimpleDelegator
     include Airbrussh::Colors
 
@@ -72,7 +72,7 @@ module Airbrussh
     end
 
     def number
-      format("%02d", @position + 1)
+      format("%02d", @position.to_i + 1)
     end
 
     def success_message

data/lib/airbrussh/rake/context.rb

@@ -8,6 +8,12 @@ module Airbrussh
     # which can be disabled via by setting
     # Airbrussh.configuration.monkey_patch_rake = false.
     #
+    # Note that this class is not thread-safe. Normally this is not a problem,
+    # but some Capistrano users are known to use `invoke` to switch the Rake
+    # task in the middle of an SSHKit thread, which causes Context to get very
+    # confused. It such scenarios Context is not reliable and may return `nil`
+    # for the `position` of a command.
+    #
     class Context
       def initialize(config=Airbrussh.configuration)
         @history = []
@@ -37,7 +43,8 @@ module Airbrussh
         first_execution
       end
 
-      # The position of the specified command in the current rake task
+      # The zero-based position of the specified command in the current rake
+      # task. May be `nil` in certain multi-threaded scenarios, so be careful!
       def position(command)
         history.index(command.to_s)
       end

data/lib/airbrussh/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Airbrussh
-  VERSION = "1.0.1".freeze
+  VERSION = "1.0.2".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: airbrussh
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Matt Brictson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-21 00:00:00.000000000 Z
+date: 2016-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sshkit
@@ -155,6 +155,7 @@ files:
 - bin/setup
 - bin/test_all.rb
 - demo.gif
+- formatting.png
 - lib/airbrussh.rb
 - lib/airbrussh/capistrano.rb
 - lib/airbrussh/capistrano/tasks.rb
@@ -189,7 +190,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.1
+rubygems_version: 2.6.4
 signing_key: 
 specification_version: 4
 summary: Airbrussh pretties up your SSHKit and Capistrano output