sshkit 1.7.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c6c3862edc2b96903f2457b6c7cb31befdb32c7b
-  data.tar.gz: 4174731b56ae910ebd531b92e00d01c1b02f47f4
+  metadata.gz: a957fee02819d1f897b5b77ee0311b7ad7d4dd9e
+  data.tar.gz: 2b84ecc03637cf6d23664fa8c00f98a165d12db4
 SHA512:
-  metadata.gz: a9d4f9d3a3ac85805a4eaa2e810ae8c000308439a25bf1fa5046748f0a2a309a335d1cce420456fd321261ffc6547ff9377d773adab315bc7f266cd5edff0a86
-  data.tar.gz: d2c81db2fd65cccb1a901096973c60d02dd26b60f49743435e03c0bc93fc58d7a16f2f90349b8593735e991ad1308007768793ccfa9d7c5cd09e48d45b38a1df
+  metadata.gz: a84d2b9ca8f28c5a32eb8a97b2b8f444f8c77885d07321eca21e6e62b2c9bfb2fbb35c59f02e6b9e920cf5ca6b91bb66e6e5965118f4269dfc2d22a5f292e950
+  data.tar.gz: 83a1190b38ca613ec201909b974c7f04ce0c9619f02493b45c29f04cde6e3bca1a98304ce5ec72a2858739e7effd3117ce11d1ea0fcc850855b8954c5d91a539

data/.travis.yml

@@ -1,6 +1,6 @@
 language: ruby
 rvm:
+  - 2.2.2
+  - 2.1.6
   - 2.0.0
-  - 1.9.3
-  - 1.9.2
 script: "rake test:units"

data/BREAKING_API_WISHLIST.md

@@ -0,0 +1,14 @@
+# Breaking API Wishlist
+
+SSHKit respects semantic versioning. This file is a place to record breaking API improvements
+which could be considered at the next major release.
+
+* Consider no longer stripping by default on `capture` [#249](https://github.com/capistrano/sshkit/pull/249)
+
+## Deprecated code which could be deleted in a future major release
+
+* [Abstract.background method](lib/sshkit/backends/abstract.rb#L43)
+* [`@stderr`, `@stdout` attrs on `Command`](lib/sshkit/command.rb#L28)
+
+## Cleanup when Ruby 1.9 support is dropped
+* `to_a` can probably be removed from `"str".lines.to_a`, since `"str".lines` returns an `Array` under Ruby 2

data/CHANGELOG.md

@@ -8,6 +8,80 @@ appear at the top.
   * Add your entries below here, remember to credit yourself however you want
     to be credited!
 
+## 1.8.0
+
+  * add SSHKit::Backend::ConnectionPool#close_connections
+    [PR #285](https://github.com/capistrano/sshkit/pull/285)
+    @akm
+  * Clean up rubocop lint warnings
+    [PR #275](https://github.com/capistrano/sshkit/pull/275)
+    @cshaffer
+    * Prepend unused parameter names with an underscore
+    * Prefer “safe assignment in condition”
+    * Disambiguate regexp literals with parens
+    * Prefer `sprintf` over `String#%`
+    * No longer shadow `caller_line` variable in `DeprecationLogger`
+    * Rescue `StandardError` instead of `Exception`
+    * Remove useless `private` access modifier in `TestAbstract`
+    * Disambiguate block operator with parens
+    * Disambiguate between grouped expression and method params
+    * Remove assertion in `TestHost#test_assert_hosts_compare_equal` that compares something with itself
+  * Export environment variables and execute command in a subshell.
+    [PR #273](https://github.com/capistrano/sshkit/pull/273)
+    @kuon
+  * Introduce `log_command_start`, `log_command_data`, `log_command_exit` methods on `Formatter`
+    [PR #257](https://github.com/capistrano/sshkit/pull/257)
+    @robd
+    * Deprecate `@stdout` and `@stderr` accessors on `Command`
+  * Add support for deprecation logging options.
+    [README](README.md#deprecation-warnings),
+    [PR #258](https://github.com/capistrano/sshkit/pull/258)
+    @robd
+  * Quote environment variable values.
+    [PR #250](https://github.com/capistrano/sshkit/pull/250)
+    @Sinjo - Chris Sinjakli
+  * Simplified formatter hierarchy.
+    [PR #248](https://github.com/capistrano/sshkit/pull/248)
+    @robd
+    * `SimpleText` formatter now extends `Pretty`, rather than duplicating.
+  * Hide ANSI color escape sequences when outputting to a file.
+    [README](README.md#output-colors),
+    [Issue #245](https://github.com/capistrano/sshkit/issues/245),
+    [PR #246](https://github.com/capistrano/sshkit/pull/246)
+    @robd
+    * Now only color the output if it is associated with a tty,
+      or the `SSHKIT_COLOR` environment variable is set.
+  * Removed broken support for assigning an `IO` to the `output` config option.
+    [Issue #243](https://github.com/capistrano/sshkit/issues/243),
+    [PR #244](https://github.com/capistrano/sshkit/pull/244)
+    @robd
+    * Use `SSHKit.config.output = SSHKit::Formatter::SimpleText.new($stdin)` instead
+  * Added support for `:interaction_handler` option on commands.
+    [PR #234](https://github.com/capistrano/sshkit/pull/234),
+    [PR #242](https://github.com/capistrano/sshkit/pull/242)
+    @robd
+  * Removed partially supported `TRACE` log level.
+    [2aa7890](https://github.com/capistrano/sshkit/commit/2aa78905f0c521ad9f697e7a4ed04ba438d5ee78)
+    @robd
+  * Add support for the `:strip` option to the `capture` method and strip by default on the `Local` backend.
+    [PR #239](https://github.com/capistrano/sshkit/pull/239),
+    [PR #249](https://github.com/capistrano/sshkit/pull/249)
+    @robd
+    * The `Local` backend now strips by default to be consistent with the `Netssh` one.
+    * This reverses change [7d15a9a](https://github.com/capistrano/sshkit/commit/7d15a9aebfcc43807c8151bf6f3a4bc038ce6218) to the `Local` capture API to remove stripping by default.
+    * If you require the raw, unstripped output, pass the `strip: false` option: `capture(:ls, strip: false)`
+  * Simplified backend hierarchy.
+    [PR #235](https://github.com/capistrano/sshkit/pull/235),
+    [PR #237](https://github.com/capistrano/sshkit/pull/237)
+    @robd
+    * Moved duplicate implementations of `make`, `rake`, `test`, `capture`, `background` on to `Abstract` backend.
+    * Backend implementations now only need to implement `execute_command`, `upload!` and `download!`
+    * Removed `Printer` from backend hierarchy for `Local` and `Netssh` backends (they now just extend `Abstract`)
+    * Removed unused `Net::SSH:LogLevelShim`
+  * Removed dependency on the `colorize` gem. SSHKit now implements its own ANSI color logic, with no external dependencies. Note that SSHKit now only supports the `:bold` or plain modes. Other modes will be gracefully ignored. [#263](https://github.com/capistrano/sshkit/issues/263)
+  * New API for setting the formatter: `use_format`. This differs from `format=` in that it accepts options or arguments that will be passed to the formatter's constructor. The `format=` syntax will be deprecated in a future release. [#295](https://github.com/capistrano/sshkit/issues/295)
+  * SSHKit now immediately raises a `NameError` if you try to set a formatter that does not exist. [#295](https://github.com/capistrano/sshkit/issues/295)
+
 ## 1.7.1
 
   * Fix a regression in 1.7.0 that caused command completion messages to be removed from log output. @mattbrictson

data/CONTRIBUTING.md

@@ -2,3 +2,46 @@
 
  * [**Don't** push your pull request](http://www.igvita.com/2011/12/19/dont-push-your-pull-requests/)
  * [**Do** write a good commit message](http://365git.tumblr.com/post/3308646748/writing-git-commit-messages)
+
+## Ruby versions
+
+You can see the current ruby versions we support in [.travis.yml](.travis.yml).
+Obviously, any language features you use must be available in the oldest version we support.
+Therefore, it's often helpful to develop / test against the oldest version to avoid accidentally
+using unsupported features.
+
+## Tests
+
+SSHKit has a unit test suite and a functional test suite. Some functional tests run against
+[Vagrant](https://www.vagrantup.com/) VMs. If possible, you should make sure that the
+tests pass for each commit by running `rake` in the sshkit directory. This is in case we
+need to cherry pick commits or rebase. You should ensure the tests pass, (preferably on
+the minimum and maximum ruby version), before creating a PR.
+
+Pull requests are much more likely to be accepted if you write a tests for the new functionality
+you are adding. If you are fixing a bug, it would be great if you could add a test to
+expose the bug you are fixing to show that the behaviour is fixed by your changes.
+
+We use [Travis CI](https://travis-ci.org/capistrano/sshkit) to run the tests on different
+ruby versions.
+
+**The Travis build does not run the functional tests,
+so make sure all the tests pass locally before creating your PR.**
+
+## Changelog
+
+Most changes should have an accompanying entry in the [CHANGELOG](CHANGELOG.md), unless they
+are minor documentation / config changes. This is incredibly important so that our users can
+see the affect of new versions without having to trawl through the commits.
+
+## Breaking changes
+
+We adhere to [semver](http://semver.org/) so breaking changes will require a major release.
+For breaking changes, it would normally be helpful to discuss them by raising a 'Proposal' issue
+or PR with examples of the new API you're proposing
+[before doing a lot of work](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/).
+Bear in mind that breaking changes may require many hundreds / thousands of users to update their
+code.
+
+You can use the [BREAKING_API_WISHLIST](BREAKING_API_WISHLIST.md) to record issues / PRs where
+API changes have been discussed, and not implemented.

data/EXAMPLES.md

@@ -2,59 +2,71 @@
 
 ## Run a command as a different user
 
-    on hosts do |host|
-      as 'www-data' do
-        puts capture(:whoami)
-      end
-    end
+```ruby
+on hosts do |host|
+  as 'www-data' do
+    puts capture(:whoami)
+  end
+end
+```
 
 ## Run with default environmental variables
 
-    SSHKit.config.default_env = { path: '/usr/local/libexec/bin:$PATH' }
-    on hosts do |host|
-      puts capture(:env)
-    end
+```ruby
+SSHKit.config.default_env = { path: '/usr/local/libexec/bin:$PATH' }
+on hosts do |host|
+  puts capture(:env)
+end
+```
 
 ## Run a command in a different directory
 
-    on hosts do |host|
-      within '/var/log' do
-        puts capture(:head, '-n5', 'messages')
-      end
-    end
+```ruby
+on hosts do |host|
+  within '/var/log' do
+    puts capture(:head, '-n5', 'messages')
+  end
+end
+```
 
 ## Run a command with specific environmental variables
 
-    on hosts do |host|
-      with rack_env: :test do
-        puts capture("env | grep RACK_ENV")
-      end
-    end
+```ruby
+on hosts do |host|
+  with rack_env: :test do
+    puts capture("env | grep RACK_ENV")
+  end
+end
+```
 
 ## Print some arbitrary output with the logging methods
 
-    on hosts do |host|
-      f = '/some/file'
-      if test("[ -d #{f} ]")
-        execute :touch, f
-      else
-        info "#{f} already exists on #{host}!"
-      end
-    end
+```ruby
+on hosts do |host|
+  f = '/some/file'
+  if test("[ -d #{f} ]")
+    execute :touch, f
+  else
+    info "#{f} already exists on #{host}!"
+  end
+end
+```
 
 The `debug()`, `info()`, `warn()`, `error()` and `fatal()` honor the current
 log level of `SSHKit.config.output_verbosity`
 
 ## Run a command in a different directory as a different user
 
-    on hosts do |host|
-      as 'www-data' do
-        within '/var/log' do
-          puts capture(:whoami)
-          puts capture(:pwd)
-        end
-      end
+```ruby
+on hosts do |host|
+  as 'www-data' do
+    within '/var/log' do
+      puts capture(:whoami)
+      puts capture(:pwd)
     end
+  end
+end
+```
 
 This will output:
 
@@ -64,31 +76,59 @@ This will output:
 **Note:** This example is a bit misleading, as the `www-data` user doesn't
 have a shell defined, one cannot switch to that user.
 
+## Run a command which requires interaction between the client and the server
+
+```ruby
+on hosts do |host|
+  execute(:passwd, interaction_handler: {
+    '(current) UNIX password: ' => "old_pw\n",
+    'Enter new UNIX password: ' => "new_pw\n",
+    'Retype new UNIX password: ' => "new_pw\n",
+    'passwd: password updated successfully' => nil # For stdout/stderr which can be ignored, map a nil input
+  })
+end
+```
+
+## Download a file from disk
+```ruby
+on roles(:all) do
+  puts 'Downloading DB Backup File'
+  date_path = Date.today.strftime("%Y/%m/%d")
+  download! "/var/mysql-backup/#{date_path}/my-awesome-db.sql.gz", "my-awesome-db.sql.gz"
+end
+```
+
 ## Upload a file from disk
 
-    on hosts do |host|
-      upload! '/config/database.yml', '/opt/my_project/shared/database.yml'
-    end
+```ruby
+on hosts do |host|
+  upload! '/config/database.yml', '/opt/my_project/shared/database.yml'
+end
+```
 
 **Note:** The `upload!()` method doesn't honor the values of `within()`, `as()`
 etc, this will be improved as the library matures, but we're not there yet.
 
 ## Upload a file from a stream
 
-    on hosts do |host|
-      file = File.open('/config/database.yml')
-      io   = StringIO.new(....)
-      upload! file, '/opt/my_project/shared/database.yml'
-      upload! io,   '/opt/my_project/shared/io.io.io'
-    end
+```ruby
+on hosts do |host|
+  file = File.open('/config/database.yml')
+  io   = StringIO.new(....)
+  upload! file, '/opt/my_project/shared/database.yml'
+  upload! io,   '/opt/my_project/shared/io.io.io'
+end
+```
 
 The IO streaming is useful for uploading something rather than "cat"ing it,
 for example
 
-    on hosts do |host|
-      contents = StringIO.new('ALL ALL = (ALL) NOPASSWD: ALL')
-      upload! contents, '/etc/sudoers.d/yolo'
-    end
+```ruby
+on hosts do |host|
+  contents = StringIO.new('ALL ALL = (ALL) NOPASSWD: ALL')
+  upload! contents, '/etc/sudoers.d/yolo'
+end
+```
 
 This spares one from having to figure out the correct escaping sequences for
 something like "echo(:cat, '...?...', '> /etc/sudoers.d/yolo')".
@@ -98,9 +138,11 @@ etc, this will be improved as the library matures, but we're not there yet.
 
 ## Upload a directory of files
 
-    on hosts do |host|
-      upload! '.', '/tmp/mypwd', recursive: true
-    end
+```ruby
+on hosts do |host|
+  upload! '.', '/tmp/mypwd', recursive: true
+end
+```
 
 In this case the `recursive: true` option mirrors the same options which are
 available to [`Net::{SCP,SFTP}`](http://net-ssh.github.io/net-scp/).
@@ -110,25 +152,29 @@ available to [`Net::{SCP,SFTP}`](http://net-ssh.github.io/net-scp/).
 Setting global SSH options, these will be overwritten by options set on the
 individual hosts:
 
-    SSHKit::Backend::Netssh.configure do |ssh|
-      ssh.connection_timeout = 30
-      ssh.ssh_options = {
-        keys: %w(/home/user/.ssh/id_rsa),
-        forward_agent: false,
-        auth_methods: %w(publickey password)
-      }
-    end
+```ruby
+SSHKit::Backend::Netssh.configure do |ssh|
+  ssh.connection_timeout = 30
+  ssh.ssh_options = {
+    keys: %w(/home/user/.ssh/id_rsa),
+    forward_agent: false,
+    auth_methods: %w(publickey password)
+  }
+end
+```
 
 ## Run a command with a different effective group ID
 
-    on hosts do |host|
-      as user: 'www-data', group: 'project-group' do
-        within '/var/log' do
-          execute :touch, 'somefile'
-          execute :ls, '-l'
-        end
-      end
+```ruby
+on hosts do |host|
+  as user: 'www-data', group: 'project-group' do
+    within '/var/log' do
+      execute :touch, 'somefile'
+      execute :ls, '-l'
     end
+  end
+end
+```
 
 One will see that the created file is owned by the user `www-data` and the
 group `project-group`.
@@ -138,14 +184,16 @@ scripts for deployment between team members without sharing logins.
 
 ## Stack directory nestings
 
-    on hosts do
-      within "/var" do
-        puts capture(:pwd)
-        within :log do
-          puts capture(:pwd)
-        end
-      end
+```ruby
+on hosts do
+  within "/var" do
+    puts capture(:pwd)
+    within :log do
+      puts capture(:pwd)
     end
+  end
+end
+```
 
 This will output:
 
@@ -160,17 +208,34 @@ joined according to the expectations of the machine receiving the commands.
 
 ## Do not care about the host block
 
-    on hosts do
-      # The |host| argument is optional, it will
-      # be nil in the block if not passed
-    end
+```ruby
+on hosts do
+  # The |host| argument is optional, it will
+  # be nil in the block if not passed
+end
+```
+
+## Change the output formatter
 
-## Redirect all output to `/dev/null`
+```ruby
+# The default format is pretty, which outputs colored text
+SSHKit.config.format = :pretty
 
-    SSHKit.config.output = File.open('/dev/null')
+# Text with no coloring
+SSHKit.config.format = :simpletext
+
+# Red / Green dots for each completed step
+SSHKit.config.format = :dot
+
+# No output
+SSHKit.config.format = :blackhole
+```
 
 ## Implement a dirt-simple formatter class
 
+```ruby
+module SSHKit
+  module Formatter
     class MyFormatter < SSHKit::Formatter::Abstract
       def write(obj)
         case obj.is_a? SSHKit::Command
@@ -178,40 +243,53 @@ joined according to the expectations of the machine receiving the commands.
         end
       end
     end
+  end
+end
+
+# If your formatter is defined in the SSHKit::Formatter module configure with the format option:
+SSHKit.config.format = :myformatter
 
-    SSHKit.config.output = MyFormatter.new($stdout)
-    SSHKit.config.output = MyFormatter.new(SSHKit.config.output)
-    SSHKit.config.output = MyFormatter.new(File.open('log/deploy.log', 'wb'))
+# Or configure the output directly
+SSHKit.config.output = MyFormatter.new($stdout)
+SSHKit.config.output = MyFormatter.new(SSHKit.config.output)
+SSHKit.config.output = MyFormatter.new(File.open('log/deploy.log', 'wb'))
+```
 
 ## Set a password for a host.
 
-    host = SSHKit::Host.new('user@example.com')
-    host.password = "hackme"
+```ruby
+host = SSHKit::Host.new('user@example.com')
+host.password = "hackme"
 
-    on host do |host|
-      puts capture(:echo, "I don't care about security!")
-    end
+on host do |host|
+  puts capture(:echo, "I don't care about security!")
+end
+```
 
 ## Execute and raise an error if something goes wrong
 
-    on hosts do |host|
-      execute!(:echo, '"Example Message!" 1>&2; false')
-    end
+```ruby
+on hosts do |host|
+  execute(:echo, '"Example Message!" 1>&2; false')
+end
+```
 
 This will raise `SSHKit::Command::Failed` with the `#message` "Example Message!"
 which will cause the command to abort.
 
 ## Make a test, or run a command which may fail without raising an error:
 
-    on hosts do |host|
-      if test "[ -d /opt/sites ]"
-        within "/opt/sites" do
-          execute :git, :pull
-        end
-      else
-        execute :git, :clone, 'some-repository', '/opt/sites'
-      end
+```ruby
+on hosts do |host|
+  if test "[ -d /opt/sites ]"
+    within "/opt/sites" do
+      execute :git, :pull
     end
+  else
+    execute :git, :clone, 'some-repository', '/opt/sites'
+  end
+end
+```
 
 The `test()` command behaves exactly the same as execute however will return
 false if the command exits with a non-zero exit (as `man 1 test` does). As it
@@ -219,24 +297,28 @@ returns boolean it can be used to direct the control flow within the block.
 
 ## Do something different on one host, or another depending on a host property
 
-    host1 = SSHKit::Host.new 'user@example.com'
-    host2 = SSHKit::Host.new 'user@example.org'
-
-    on hosts do |host|
-      target = "/var/www/sites/"
-      if host.hostname =~ /org/
-        target += "dotorg"
-      else
-        target += "dotcom"
-      end
-      execute! :git, :clone, "git@git.#{host.hostname}", target
-    end
+```ruby
+host1 = SSHKit::Host.new 'user@example.com'
+host2 = SSHKit::Host.new 'user@example.org'
+
+on hosts do |host|
+  target = "/var/www/sites/"
+  if host.hostname =~ /org/
+    target += "dotorg"
+  else
+    target += "dotcom"
+  end
+  execute! :git, :clone, "git@git.#{host.hostname}", target
+end
+```
 
 ## Connect to a host in the easiest possible way
 
-    on 'example.com' do |host|
-      execute :uptime
-    end
+```ruby
+on 'example.com' do |host|
+  execute :uptime
+end
+```
 
 This will resolve the `example.com` hostname into a `SSHKit::Host` object, and
 try to pull up the correct configuration for it.
@@ -247,13 +329,15 @@ try to pull up the correct configuration for it.
 If the command you attempt to call contains a space character it won't be
 mapped:
 
-    Command.new(:git, :push, :origin, :master).to_s
-    # => /usr/bin/env git push origin master
-    # (also: execute(:git, :push, :origin, :master)
+```ruby
+Command.new(:git, :push, :origin, :master).to_s
+# => /usr/bin/env git push origin master
+# (also: execute(:git, :push, :origin, :master)
 
-    Command.new("git push origin master").to_s
-    # => git push origin master
-    # (also: execute("git push origin master"))
+Command.new("git push origin master").to_s
+# => git push origin master
+# (also: execute("git push origin master"))
+```
 
 This can be used to access shell builtins (such as `if` and `test`)
 
@@ -262,14 +346,16 @@ This can be used to access shell builtins (such as `if` and `test`)
 
 An extension of the behaviour above, if you write a command like this:
 
-    c = Command.new <<-EOCOMMAND
-      if test -d /var/log
-      then echo "Directory Exists"
-      fi
-    EOCOMMAND
-    c.to_s
-    # => if test -d /var/log; then echo "Directory Exists; fi
-    # (also: execute <<- EOCOMMAND........))
+```ruby
+c = Command.new <<-EOCOMMAND
+  if test -d /var/log
+  then echo "Directory Exists"
+  fi
+EOCOMMAND
+c.to_s
+# => if test -d /var/log; then echo "Directory Exists; fi
+# (also: execute <<- EOCOMMAND........))
+```
 
 **Note:** The logic which reformats the script into a oneliner may be naïve, but in all
 known test cases, it works. The key thing is that `if` is not mapped to
@@ -279,31 +365,35 @@ known test cases, it works. The key thing is that `if` is not mapped to
 
 Into the `Rakefile` simply put something like:
 
-    require 'sshkit/dsl'
+```ruby
+require 'sshkit/dsl'
 
-    SSHKit.config.command_map[:rake] = "./bin/rake"
+SSHKit.config.command_map[:rake] = "./bin/rake"
 
-    desc "Deploy the site, pulls from Git, migrate the db and precompile assets, then restart Passenger."
-    task :deploy do
-      on "example.com" do |host|
-        within "/opt/sites/example.com" do
-          execute :git, :pull
-          execute :bundle, :install, '--deployment'
-          execute :rake, 'db:migrate'
-          execute :rake, 'assets:precompile'
-          execute :touch, 'tmp/restart.txt'
-        end
-      end
+desc "Deploy the site, pulls from Git, migrate the db and precompile assets, then restart Passenger."
+task :deploy do
+  on "example.com" do |host|
+    within "/opt/sites/example.com" do
+      execute :git, :pull
+      execute :bundle, :install, '--deployment'
+      execute :rake, 'db:migrate'
+      execute :rake, 'assets:precompile'
+      execute :touch, 'tmp/restart.txt'
     end
+  end
+end
+```
 
 ## Using without the DSL
 
 The *Coordinator* will resolve all hosts into *Host* objects, you can mix and
 match.
 
-    Coordinator.new("one.example.com", SSHKit::Host.new('two.example.com')).each in: :sequence do
-      puts capture :uptime
-    end
+```ruby
+Coordinator.new("one.example.com", SSHKit::Host.new('two.example.com')).each in: :sequence do
+  puts capture :uptime
+end
+```
 
 You might also look at `./lib/sshkit/dsl.rb` where you can see almost the
 exact code as above, which implements the `on()` method.
@@ -312,23 +402,25 @@ exact code as above, which implements the `on()` method.
 
 Implemented since `v0.0.6`
 
-    servers = %w{one.example.com two.example.com
-                 three.example.com four.example.com}.collect do |s|
-      h = SSHKit::Host.new(s)
-      if s.match /(one|two)/
-        h.properties.roles = [:web]
-      else
-        h.properties.roles = [:app]
-      end
-    end
-
-    on servers do |host|
-      if host.properties.roles.include?(:web)
-        # Do something pertinent to web servers
-      elsif host.properties.roles.include?(:app)
-        # Do something pertinent to application servers
-      end
-    end
+```ruby
+servers = %w{one.example.com two.example.com
+             three.example.com four.example.com}.collect do |s|
+  h = SSHKit::Host.new(s)
+  if s.match /(one|two)/
+    h.properties.roles = [:web]
+  else
+    h.properties.roles = [:app]
+  end
+end
+
+on servers do |host|
+  if host.properties.roles.include?(:web)
+    # Do something pertinent to web servers
+  elsif host.properties.roles.include?(:app)
+    # Do something pertinent to application servers
+  end
+end
+```
 
 The `SSHKit::Host#properties` is an [`OpenStruct`](http://ruby-doc.org/stdlib-1.9.3/libdoc/ostruct/rdoc/OpenStruct.html)
 which is not verified or validated in any way, it is up to you, or your
@@ -338,16 +430,20 @@ library to attach meanings or conventions to this mechanism.
 
 Replace `on` with `run_locally`
 
-    run_locally do
-      within '/tmp' do
-        execute :whoami
-      end
-    end
+```ruby
+run_locally do
+  within '/tmp' do
+    execute :whoami
+  end
+end
+```
 
 You can achieve the same thing with `on(:local)`
 
-    on(:local) do
-      within '/tmp' do
-        execute :whoami
-      end
-    end
+```ruby
+on(:local) do
+  within '/tmp' do
+    execute :whoami
+  end
+end
+```