guard 1.4.0 → 2.18.0

data/README.md

@@ -1,234 +1,109 @@
-Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png?branch=master)](http://travis-ci.org/guard/guard)
-=====
+# Guard
 
-Guard is a command line tool to easily handle events on file system modifications.
+**IMPORTANT: Please upgrade to Ruby >= 2.4 before installing Guard! To install for older versions, update Bundler at least 1.12: `gem update bundler` and Bundler should correctly resolve to earlier gems for your given Ruby version.**
 
-This document contains a lot of information, please take your time and read these instructions carefully. If you have
-any questions, ask them in our [Google group](http://groups.google.com/group/guard-dev) or on `#guard`
-(irc.freenode.net).
+- [Ruby 2.1 is officially outdated and unsupported!](https://www.ruby-lang.org/en/news/2016/03/30/ruby-2-1-9-released/)
+- [Ruby 2.2 is officially outdated and unsupported!](https://www.ruby-lang.org/en/news/2018/06/20/support-of-ruby-2-2-has-ended/)
+- [Ruby 2.3 is officially outdated and unsupported!](https://www.ruby-lang.org/en/news/2019/03/31/support-of-ruby-2-3-has-ended/)
 
-Information on advanced topics like creating your own Guard plugin, programatic use of Guard, hooks and callbacks and
-more can be found in the [Guard wiki](https://github.com/guard/guard/wiki).
+:exclamation: Guard is currently accepting more maintainers. Please [read this](https://github.com/guard/guard/wiki/Maintainers) if you're interested in joining the team.
 
-Before you file an issue, make sure you have read the _[file an issue](#file-an-issue)_ section that contains some
-important information.
+[![Gem Version](https://img.shields.io/gem/v/guard.svg?style=flat)](https://rubygems.org/gems/guard) [![Build Status](https://travis-ci.org/guard/guard.svg?branch=master)](https://travis-ci.org/guard/guard) [![Code Climate](https://codeclimate.com/github/guard/guard/badges/gpa.svg)](https://codeclimate.com/github/guard/guard) [![Test Coverage](https://codeclimate.com/github/guard/guard/badges/coverage.svg)](https://codeclimate.com/github/guard/guard) [![Inline docs](http://inch-ci.org/github/guard/guard.svg)](http://inch-ci.org/github/guard/guard) [![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)
 
-Features
---------
+<img src="http://f.cl.ly/items/0A0M3W2x3I1P450z341U/guard-Icon.png" alt="Guard Icon" align="right" />
+Guard automates various tasks by running custom rules whenever file or directories are modified.
 
-* File system changes handled by our awesome [Listen](https://github.com/guard/listen) gem.
-* Support for visual system notifications.
-* Huge eco-system with [more than 150](https://rubygems.org/search?query=guard-) guard plugins.
-* Tested against Ruby 1.8.7, 1.9.2, 1.9.3, REE and the latest versions of JRuby & Rubinius.
-
-Screencast
-----------
-
-Ryan Bates made an excellent [RailsCast about Guard](http://railscasts.com/episodes/264-guard) and you should definitely
-watch it for a nice introduction to Guard.
-
-Installation
-------------
-
-The simplest way to install Guard is to use [Bundler](http://gembundler.com/).
-
-Add Guard to your `Gemfile`:
-
-```ruby
-group :development do
-  gem 'guard'
-end
-```
+It's frequently used by software developers, web designers, writers and other specialists to avoid mundane, repetitive actions and commands such as "relaunching" tools after changing source files or configurations.
 
-and install it by running Bundler:
+Common use cases include: an IDE replacement, web development tools, designing "smart" and "responsive" build systems/workflows, automating various project tasks and installing/monitoring various system services.
 
-```bash
-$ bundle
-```
+For a full categorized list of known Guard plugins, look here: https://github.com/guard/guard/wiki/Guard-Plugins
 
-Generate an empty `Guardfile` with:
+If you have
+any questions about Guard or want to share some information with the Guard community, please go to one of
+the following places:
 
-```bash
-$ guard init
-```
-
-**It's important that you always run Guard through Bundler to avoid errors.** If you're getting sick of typing `bundle exec` all
-the time, try the [Rubygems Bundler](https://github.com/mpapis/rubygems-bundler).
+* [Guard Wiki](https://github.com/guard/guard/wiki)
+* [Google+ community](https://plus.google.com/communities/110022199336250745477).
+* [Google group](http://groups.google.com/group/guard-dev).
+* [StackOverflow](http://stackoverflow.com/questions/tagged/guard).
+* IRC channel `#guard` (irc.freenode.net) for chatting.
 
-## OS X
+Before you file an issue, make sure you have read the _[known issues](#issues)_ and _[file an issue](#file-an-issue)_ sections that contains some important information.
 
-You may want to install the [rb-fsevent](https://github.com/thibaudgg/rb-fsevent) gem to make use of file change events
-and don't rely on polling by adding the gem to your `Gemfile` and install it with Bundler:
+## Features
 
-```ruby
-group :development do
-  gem 'rb-fsevent', :require => false
-end
-```
-
-## Linux
-
-You may want to install the [rb-inotify](https://github.com/nex3/rb-inotify) gem to make use of file change events and
-don't rely on polling by adding the gem to your `Gemfile` and install it with Bundler:
-
-```ruby
-group :development do
-  gem 'rb-inotify', :require => false
-end
-```
-
-## Windows
-
-You may want to install the [wdm](https://github.com/Maher4Ever/wdm) gem to make use of file change events and don't
-rely on polling by adding the gem to your `Gemfile` and install it with Bundler:
-
-```ruby
-group :development do
-  gem 'wdm', :require => false
-end
-```
-
-Please note that you have to use at least on Ruby 1.9.2 for using WDM.
-
-If you want colors in your terminal, you'll have to add the [win32console](https://rubygems.org/gems/win32console) gem
-to your `Gemfile` and install it with Bundler:
-
-```ruby
-group :development do
-  gem 'win32console'
-end
-```
-
-### System notifications
+* File system changes handled by our awesome [Listen](https://github.com/guard/listen) gem.
+* Support for visual system notifications.
+* Huge eco-system with [more than 300](https://rubygems.org/search?query=guard-) Guard plugins.
+* Tested against the latest Ruby 2.4.x, 2.5.x, 2.6.x, JRuby & Rubinius. See [`.travis-ci.yml`](https://github.com/guard/guard/blob/master/.travis.yml) for the exact versions.
 
-You can configure Guard to make use of the following system notification libraries, but it's strongly recommended
-to use either Ruby GNTP, Libnotify or Notifu:
+## Screencast
 
-#### Ruby GNTP
+Two nice screencasts are available to help you get started:
 
-* Runs on Mac OS X, Linux and Windows
-* Supports [Growl](http://growl.info/) version >= 1.3, [Growl for Linux](http://mattn.github.com/growl-for-linux/),
-  [Growl for Windows](http://www.growlforwindows.com/gfw/default.aspx) and
-  [Snarl](https://sites.google.com/site/snarlapp/home)
+* [Guard](http://railscasts.com/episodes/264-guard) on RailsCast.
+* [Guard is Your Best Friend](http://net.tutsplus.com/tutorials/tools-and-tips/guard-is-your-best-friend) on Net Tuts+.
 
-The [ruby_gntp](https://rubygems.org/gems/ruby_gntp) gem sends system notifications over the network with the
-[Growl Notification Transport Protocol](http://www.growlforwindows.com/gfw/help/gntp.aspx) and supports local and
-remote notifications. To have the images be displayed, you have to use `127.0.0.1` instead of `localhost` in your GTNP
-configuration.
+## Installation
 
-Guard supports multiple notification channels for customizing each notification type. For Growl on Mac OS X you need
-to have at least version 1.3 installed.
+The simplest way to install Guard is to use [Bundler](http://bundler.io).
 
-To use `ruby_gntp` you have to add it to your `Gemfile` and run bundler:
+Add Guard (and any other dependencies) to a `Gemfile` in your project’s root:
 
 ```ruby
 group :development do
-  gem 'ruby_gntp'
+  gem 'guard'
 end
 ```
 
-#### Growl
+then install it by running Bundler:
 
-* Runs on Mac OS X
-* Supports all [Growl](http://growl.info/) versions
-
-The [growl](https://rubygems.org/gems/growl) gem is compatible with all versions of Growl and uses a command line tool
-[growlnotify](http://growl.info/extras.php#growlnotify) that must be separately downloaded and installed. The version of
-the command line tool must match your Growl version. The `growl` gem does **not** support multiple notification
-channels.
-
-You have to download the installer for `growlnotify` from the [Growl download section](http://growl.info/downloads).
-
-To use `growl` you have to add it to your `Gemfile` and run bundler:
-
-```ruby
-group :development do
-  gem 'growl'
-end
+```bash
+$ bundle
 ```
 
-#### Libnotify
-
-* Runs on Linux, FreeBSD, OpenBSD and Solaris
-* Supports [Libnotify](http://developer.gnome.org/libnotify/)
-
-The [libnotify](https://rubygems.org/gems/libnotify) gem supports the Gnome libnotify notification daemon, but it can be
-used on other window managers as well. You have to install the `libnotify-bin` package with your favorite package
-manager.
-
-To use `libnotify` you have to add it to your `Gemfile` and run bundler:
+Generate an empty `Guardfile` with:
 
-```ruby
-group :development do
-  gem 'libnotify'
-end
+```bash
+$ bundle exec guard init
 ```
 
-If you are unable to build the `libnotify` gem on your system, Guard
-also has a built in notifier - `notifysend` - that shells out to the
-`notify-send` utility that comes with `libnotify-bin`.
-
-#### Notifu
-
-* Runs on Windows
-* Supports [Notifu](http://www.paralint.com/projects/notifu/)
-
-The [rb-notifu](https://rubygems.org/gems/rb-notifu) gem supports Windows system tray notifications.
-
-To use `rb-notifu` you have to add it to your `Gemfile` and run bundler:
+Run Guard through Bundler with:
 
-```ruby
-group :development do
-  gem 'rb-notifu'
-end
+```bash
+$ bundle exec guard
 ```
 
-#### GrowlNotify
+If you are on Mac OS X and have problems with either Guard not reacting to file
+changes or Pry behaving strange, then you should [add proper Readline support
+to Ruby on macOS](https://github.com/guard/guard/wiki/Add-Readline-support-to-Ruby-on-Mac-OS-X).
 
-* Runs on Mac OS X
-* Supports [Growl](http://growl.info/) version >= 1.3
-* Doesn't support JRuby and MacRuby.
-* Doesn't work when forking, e.g. with [Spork](https://github.com/sporkrb/spork).
+## Avoiding gem/dependency problems
 
-The [growl_notify](https://rubygems.org/gems/growl_notify) gem uses AppleScript to send Growl notifications.
-The gem needs a native C extension to make use of AppleScript and does not run on JRuby and MacRuby.
+**It's important that you always run Guard through Bundler to avoid errors.**
 
-Guard supports multiple notification channels for customizing each notification type and you need to have at least
-Growl version 1.3 installed.
+If you're getting sick of typing `bundle exec` all the time, try one of the following:
 
-To use `growl_notify` you have to add it to your `Gemfile` and run bundler:
+* (Recommended) Running `bundle binstub guard` will create `bin/guard` in your
+  project, which means running `bin/guard` (tab completion will save you a key
+  stroke or two) will have the exact same result as `bundle exec guard`.
 
-```ruby
-group :development do
-  gem 'growl_notify'
-end
-```
-
-#### Terminal Notifier
-
-* Runs on Mac OS X 10.8 only
+* Or, you can `alias be="bundle exec"` in your `.bashrc` or similar and the execute only `be guard`.
+  **Protip**: It will work for all comands executed in `bundle exec` context!
 
-The [terminal-notifier-guard](https://github.com/Springest/terminal-notifier-guard) sends notifications to the OS X
-Notification Center.
-
-To use `terminal-notifier-guard` you have to add it to your `Gemfile` and run bundler:
-
-```ruby
-group :development do
-  gem 'terminal-notifier-guard'
-end
-```
 
-#### Emacs
+* Or, for RubyGems >= 2.2.0 (at least, though the more recent the better),
+  simply set the `RUBYGEMS_GEMDEPS` environment variable to `-` (for autodetecting
+  the Gemfile in the current or parent directories) or set it to the path of your Gemfile.
 
-* Runs on any platform with Emacs + emacsclient (http://www.emacswiki.org/emacs/EmacsClient)
+(To upgrade RubyGems from RVM, use the `rvm rubygems` command).
 
-### Tmux
+*NOTE: this Rubygems feature is still under development still lacks many features of bundler*
 
-* To use Tmux notifications, you have to start Guard within a [tmux](http://tmux.sourceforge.net/) session.
+* Or, for RubyGems < 2.2.0 check out the [Rubygems Bundler](https://github.com/rvm/rubygems-bundler).
 
-Add Guard plugins
------------------
+## Add Guard plugins
 
 Guard is now ready to use and you should add some Guard plugins for your specific use. Start exploring the many Guard
 plugins available by browsing the [Guard organization](https://github.com/guard) on GitHub or by searching for `guard-`
@@ -245,605 +120,68 @@ end
 See the init section of the Guard usage below to see how to install the supplied plugin template that you can install and
 to suit your needs.
 
-Usage
------
+## Usage
 
 Guard is run from the command line. Please open your terminal and go to your project work directory.
 
-### Help
-
-You can always get help on the available tasks with the `help` task:
-
-```bash
-$ guard help
-```
-
-To request more detailed help on a specific task is simple: just appending the task name to the help task.
-For example, to get help for the `start` task, simply run:
-
-```bash
-$ guard help start
-```
-
-### Init
-
-You can generate a Guardfile and have all installed plugins be automatically added into
-it by running the `init` task without any option:
-
-```bash
-$ guard init
-```
-
-You can also specify the name of an installed plugin to only get that plugin template
-in the generated Guardfile:
-
-```bash
-$ guard init <guard-name>
-```
-
-You can also specify the names of multiple plugins to only get those plugin templates
-in the generated Guardfile:
-
-```bash
-$ guard init <guard1-name> <guard2-name>
-```
-
-You can also define your own templates in `~/.guard/templates/` which can be appended in the same way to your existing
-`Guardfile`:
-
-```bash
-$ guard init <template-name>
-```
-
-**Note**: If you already have a `Guardfile` in the current directory, the `init` task can be used
-to append a supplied template from an installed plugin to your existing `Guardfile`.
-
-#### `-b`/`--bare` option
-
-You can generate an empty `Guardfile` by running the `init` task with the bare
-option:
-
-```bash
-$ guard init --bare
-$ guard init -b # shortcut
-```
+Look here for a full [list of Guard commands](https://github.com/guard/guard/wiki/List-of-Guard-Commands)
 
 ### Start
 
 Just launch Guard inside your Ruby or Rails project with:
 
 ```bash
-$ guard
-```
-
-Guard will look for a `Guardfile` in your current directory. If it does not find one, it will look in your `$HOME`
-directory for a `.Guardfile`.
-
-#### `-c`/`--clear` option
-
-The shell can be cleared after each change:
-
-```bash
-$ guard --clear
-$ guard -c # shortcut
-```
-
-#### `-n`/`--notify` option
-
-System notifications can be disabled:
-
-```bash
-$ guard --notify false
-$ guard -n f # shortcut
-```
-
-Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`.
-
-#### `-g`/`--group` option
-
-Only certain plugin groups can be run:
-
-```bash
-$ guard --group group_name another_group_name
-$ guard -g group_name another_group_name # shortcut
-```
-
-See the Guardfile DSL below for creating groups.
-
-#### `-d`/`--debug` option
-
-Guard can display debug information which can be very usefull for plugins
-developers with:
-
-```bash
-$ guard --debug
-$ guard -d # shortcut
-```
-
-#### `-w`/`--watchdir` option
-
-Guard can watch any directory instead of the current directory:
-
-```bash
-$ guard --watchdir ~/your/fancy/project
-$ guard -w ~/your/fancy/project # shortcut
-```
-
-#### `-G`/`--guardfile` option
-
-Guard can use a `Guardfile` not located in the current directory:
-
-```bash
-$ guard --guardfile ~/.your_global_guardfile
-$ guard -G ~/.your_global_guardfile # shortcut
-```
-
-#### `-i`/`--no-interactions` option
-
-Turn off completely any Guard terminal interactions with:
-
-```bash
-$ guard start -i
-$ guard start --no-interactions
-```
-
-#### `-B`/`--no-bundler-warning` option
-
-Skip Bundler warning when a Gemfile exists in the project directory but Guard is not run with Bundler.
-
-```bash
-$ guard start -B
-$ guard start --no-bundler-warning
-```
-
-#### `-l`/`--latency` option
-
-Overwrite Listen's default latency, useful when your hard-drive / system is slow.
-
-```bash
-$ guard start -l 1.5
-$ guard start --latency 1.5
-```
-
-#### `-p`/`--force-polling` option
-
-Force Listen polling listener usage.
-
-```bash
-$ guard start -p
-$ guard start --force-polling
+$ bundle exec guard
 ```
 
-### List
+Guard will look for a `Guardfile` or `guardfile.rb` in your current directory. If it does not find one, it will look
+in your `$HOME` directory for a `.Guardfile`.
 
-You can list the available plugins with the `list` task:
+Please look here to see all the [command line options for Guard](https://github.com/guard/guard/wiki/Command-line-options-for-Guard)
 
-```bash
-$ guard list
-
-Available guards:
-   coffeescript
-   compass
-   cucumber
-   jammit
-   ronn
-   rspec *
-   spork
-   yard
-See also https://github.com/guard/guard/wiki/List-of-available-Guards
-* denotes ones already in your Guardfile
-```
-
-### Show
-
-You can show the structure of the groups and their plugins with the `show` task:
-
-```bash
-$ guard show
-
-(global):
-  shell
-Group backend:
-  bundler
-  rspec: cli => "--color --format doc"
-Group frontend:
-  coffeescript: output => "public/javascripts/compiled"
-  livereload
-```
-
-This shows the internal structure of the evaluated `Guardfile` or `.Guardfile`, with the `.guard.rb` file. You can
-read more about these files in the shared configuration section below.
-
-Interactions
-------------
-
-You can interact with Guard and enter commands when Guard has nothing to do. Guard understands the following commands:
-
-* `↩`:                 Run all plugins.
-* `h`, `help`:         Show a help of the available interactor commands.
-* `r`, `reload`:       Reload all plugins.
-* `c`, `change`:       Trigger a file change to the plugins.
-* `s`, `show`:         Show the plugin configurations.
-* `n`, `notification`: Toggle system notifications on and off.
-* `p`, `pause`:        Toggles the file modification listener. The prompt will change to `p>` when paused.
-                       This is useful when switching Git branches, rebase Git or change whitespace.
-* `e`, `exit`:         Stop all plugins and quit Guard.
-
-Instead of running all plugins with the `↩` key, you can also run a single plugin by entering its name:
-
-```bash
-> rspec
-```
-
-It's also possible to run all plugins within a group by entering the group name:
-
-```bash
-> frontend
-```
-
-The same applies to reloading. You can reload a plugin with the following command:
-
-```bash
-> ronn reload
-```
-
-This will reload only the Ronn plugin. You can also reload all plugins within a group:
-
-```bash
-> backend reload
-```
-
-The action and plugin/group name can have any order, so you can also write:
-
-```bash
-> reload backend
-```
-
-You can pass a list of filenames to the `change` command to trigger manually a file modification:
-
-```bash
-> change spec/guard_spec.rb
-```
-
-### Readline support
-
-With Readline enabled, you'll see a command prompt `>` when Guard is ready to accept a command. The command line
-supports history navigation with the `↑` and `↓` arrow keys, and command auto-completion with the `⇥` key.
-
-Unfortunately Readline [does not work on MRI](http://bugs.ruby-lang.org/issues/5539) on Mac OS X by default. You can
-work around the issue by installing a pure Ruby implementation:
-
-```ruby
-platforms :ruby do
-  gem 'rb-readline'
-end
-```
-
-Guard will automatically enable Readline support if your environment supports it, but you can disable Readline with the
-`interactor` DSL method or turn off completely with the `--no-interactions` option.
-
-### Coolline support
-
-With Ruby 1.9.3 you can use a [Coolline](https://github.com/Mon-Ouie/coolline) based interactor, which uses the new
-`io/console` from stdlib. Just add it to your `Gemfile`
-
-```ruby
-gem 'coolline'
-```
-
-Guard will automatically enable Coolline support if your environment supports it, but you can disable Coolline with the
-`interactor` DSL method or turn off completely with the `--no-interactions` option.
-
-### Signals
-
-You can also interact with Guard by sending POSIX signals to the Guard process (all but Windows and JRuby).
-
-#### Pause watching
-
-```bash
-$ kill -USR1 <guard_pid>
-```
-
-#### Continue watching
-
-```bash
-$ kill -USR2 <guard_pid>
-```
-
-Guardfile DSL
--------------
-
-The Guardfile DSL is evaluated as plain Ruby, so you can use normal Ruby code in your `Guardfile`.
-Guard itself provides the following DSL methods that can be used for configuration:
-
-### guard
-
-The `guard` method allows you to add a Guard plugin to your toolchain and configure it by passing the
-options after the name of the plugin:
-
-```ruby
-guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'
-```
-
-You can define the same plugin more than once:
-
-```ruby
-guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'
-guard :coffeescript, :input => 'specs', :output => 'specs'
-```
-
-### watch
-
-The `watch` method allows you to define which files are watched by a Guard:
-
-```ruby
-guard :bundler do
-  watch('Gemfile')
-end
-```
-
-String watch patterns are matched with [String#==](http://www.ruby-doc.org/core-1.9.2/String.html#method-i-3D-3D).
-You can also pass a regular expression to the watch method:
-
-```ruby
-guard :jessie do
-  watch(%r{^spec/.+(_spec|Spec)\.(js|coffee)})
-end
-```
-
-This instructs the jessie plugin to watch for file changes in the `spec` folder,
-but only for file names that ends with `_spec` or `Spec` and have a file type of `js` or `coffee`.
-
-You can easily test your watcher regular expressions with [Rubular](http://rubular.com/).
-
-When you add a block to the watch expression, you can modify the file name that has been
-detected before sending it to the plugin for processing:
-
-```ruby
-guard :rspec do
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-end
-```
-
-In this example the regular expression capture group `(.+)` is used to transform a file change
-in the `lib` folder to its test case in the `spec` folder. Regular expression watch patterns
-are matched with [Regexp#match](http://www.ruby-doc.org/core-1.9.2/Regexp.html#method-i-match).
-
-You can also launch any arbitrary command in the supplied block:
-
-```ruby
-guard :shell do
-  watch('.*') { `git status` }
-end
-```
-
-### group
-
-The `group` method allows you to group several plugins together. This comes in handy especially when you
-have a huge `Guardfile` and want to focus your development on a certain part.
-
-```ruby
-group :specs do
-  guard :rspec do
-    watch(%r{^spec/.+_spec\.rb$})
-  end
-end
-
-group :docs do
-  guard :ronn do
-    watch(%r{^man/.+\.ronn?$})
-  end
-end
-```
-
-Groups to be run can be specified with the Guard DSL option `--group` (or `-g`):
-
-```bash
-$ guard -g specs
-```
-
-Guard plugins that don't belong to a group are considered global and are always run.
+## Interactions
 
-### notification
-
-If you don't specify any notification configuration in your `Guardfile`, Guard goes through the list of available
-notifiers and takes the first that is available. If you specify your preferred library, auto detection will not take
-place:
-
-```ruby
-notification :growl
-```
-
-will select the `growl` gem for notifications. You can also set options for a notifier:
-
-```ruby
-notification :growl, :sticky => true
-```
-
-Each notifier has a slightly different set of supported options:
-
-```ruby
-notification :growl, :sticky => true, :host => '192.168.1.5', :password => 'secret'
-notification :gntp, :sticky => true, :host => '192.168.1.5', :password => 'secret'
-notification :growl_notify, :sticky => true, :priority => 0
-notification :libnotify, :timeout => 5, :transient => true, :append => false, :urgency => :critical
-notification :notifu, :time => 5, :nosound => true, :xp => true
-notification :emacs
-```
-
-It's possible to use more than one notifier. This allows you to configure different notifiers for different OS if your
-project is developed cross-platform or if you like to have local and remote notifications.
-
-Notifications can also be turned off in the `Guardfile`, in addition to setting the environment variable `GUARD_NOTIFY`
-or using the cli switch `-n`:
-
-```ruby
-notification :off
-```
-
-### interactor
-
-You can disable the interactor auto detection and select a specific implementation:
-
-```ruby
-interactor :coolline
-interactor :readline
-interactor :simple
-```
-
-If you do not need the keyboard interactions with Guard at all, you can turn them off:
-
-```ruby
-interactor :off
-```
-
-### callback
-
-The `callback` method allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`,
-`run_all`, `run_on_changes`, `run_on_additions`, `run_on_modifications` and `run_on_removals` Guard plugins method.
-You can even insert more hooks inside these methods.
-
-```ruby
-guard :rspec do
-  watch(%r{^spec/.+_spec\.rb$})
-
-  callback(:start_begin) { `mate .` }
-end
-```
-
-Please see the [hooks and callbacks](https://github.com/guard/guard/wiki/Hooks-and-callbacks) page in the Guard wiki for
-more details.
-
-### ignore
-
-The `ignore` method can be used to exclude files and directories from the set of files being watched. Let's say you have
-used the `watch` method to monitor a directory, but you are not interested in changes happening to images, you could use
-the ignore method to exclude them.
-
-This comes in handy when you have large amounts of non-source data in you project. By default
-[`.rbx`, `.bundle`, `.git`, `.svn`, `log`, `tmp`, `vendor`](https://github.com/guard/listen/blob/master/lib/listen/directory_record.rb#L14)
-are ignored.
-
-Please note that method only accept regexps. More on the
-[Listen README](https://github.com/guard/listen#the-patterns-for-filtering-and-ignoring-paths).
-
-```ruby
-ignore %r{^ignored/path/}, /public/
-```
-
-### filter
-
-The `filter` method allows you to focus by filtering files and directories without having to specify them by hand in the
-`watch` method. E.g. if you are watching multiple directories but only interested in changes to the Ruby files, then use
-the `filter` method.
-
-Please note that method only accept regexps. More on the
-[Listen README](https://github.com/guard/listen#the-patterns-for-filtering-and-ignoring-paths).
-
-```ruby
-filter /\.txt$/, /.*\.zip/
-```
-
-### Example
-
-```ruby
-ignore %r{^ignored/path/}, /public/
-filter /\.txt$/, /.*\.zip/
-
-notification :growl_notify
-notification :gntp, :host => '192.168.1.5'
-
-group :backend do
-  guard :bundler do
-    watch('Gemfile')
-  end
-
-  guard :rspec, :cli => '--color --format doc' do
-    watch(%r{^spec/.+_spec\.rb$})
-    watch(%r{^lib/(.+)\.rb$})         { |m| "spec/lib/#{m[1]}_spec.rb" }
-    watch(%r{^spec/models/.+\.rb$})   { ["spec/models", "spec/acceptance"] }
-    watch(%r{^spec/.+\.rb$})          { `say hello` }
-    watch('spec/spec_helper.rb')      { "spec" }
-  end
-end
-
-group :frontend do
-  guard :coffeescript, :output => 'public/javascripts/compiled' do
-    watch(%r{^app/coffeescripts/.+\.coffee$})
-  end
-
-  guard :livereload do
-    watch(%r{^app/.+\.(erb|haml)$})
-  end
-end
-```
-
-Shared configurations
----------------------
-
-You may optionally place a `.Guardfile` in your home directory to use it across multiple projects. It's evaluated when
-you have no `Guardfile` in your current directory.
-
-If a `.guard.rb` is found in your home directory, it will be appended to the `Guardfile` in your current directory.
-This can be used for tasks you want guard to handle but other users probably don't.
-
-For example, indexing your source tree with [Ctags](http://ctags.sourceforge.net):
-
-```ruby
-guard :shell do
-  watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
-end
-```
+Please read how to [interact with Guard](https://github.com/guard/guard/wiki/Interacting-with-Guard) on the console and which [signals](https://github.com/guard/guard/wiki/Interacting-with-Guard#guard-signals) Guard accepts
 
-File an issue
--------------
 
-You can report bugs and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
+## Guardfile DSL
 
-**Please don't ask question in the issue tracker**, instead ask them in our
-[Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
+For details on extending your `Guardfile` look at [Guardfile examples](https://github.com/guard/guard/wiki/Guardfile-examples) or look at a list of commands [Guardfile-DSL / Configuring-Guard](https://github.com/guard/guard/wiki/Guardfile-DSL---Configuring-Guard)
 
-Try to figure out where the issue belongs to: Is it an issue with Guard itself or with a Guard plugin you're
-using?
+## Issues
 
-When you file a bug, please try to follow these simple rules if applicable:
+Before reporting a problem, please read how to [File an issue](https://github.com/guard/guard/blob/master/CONTRIBUTING.md#file-an-issue).
 
-* Make sure you run Guard with `bundle exec` first.
-* Add debug information to the issue by running Guard with the `--debug` option.
-* Add your `Guardfile` and `Gemfile` to the issue.
-* Make sure that the issue is reproducible with your description.
+## Development / Contributing
 
-**It's most likely that your bug gets resolved faster if you provide as much information as possible!**
+See the [Contributing Guide](https://github.com/guard/guard/blob/master/CONTRIBUTING.md#development).
 
-Development [![Dependency Status](https://gemnasium.com/guard/guard.png?branch=master)](https://gemnasium.com/guard/guard) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/guard/guard)
------------
+## Releasing
 
-* Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
-* Source hosted at [GitHub](https://github.com/guard/guard).
+### Prerequisites
 
-Pull requests are very welcome! Please try to follow these simple rules if applicable:
+* You must have commit rights to the GitHub repository.
+* You must have push rights for rubygems.org.
 
-* Please create a topic branch for every separate change you make.
-* Make sure your patches are well tested. All specs run with `rake spec:portability` must pass.
-* Update the [Yard](http://yardoc.org/) documentation.
-* Update the [README](https://github.com/guard/guard/blob/master/README.md).
-* Update the [CHANGELOG](https://github.com/guard/guard/blob/master/CHANGELOG.md) for noteworthy changes.
-* Please **do not change** the version number.
+### How to release
 
-For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
-`#guard` (irc.freenode.net).
+1. Determine which would be the correct next version number according to [semver](http://semver.org/).
+1. Update the version in `./lib/guard/version.rb`.
+1. Commit the version in a single commit, the message should be "Bump VERSION to X.Y.Z".
+1. Push and open a pull request.
+1. Once CI is green, merge the pull request.
+1. Pull the changes locally and run `bundle exec rake release:full`; this will tag, push to GitHub, publish to rubygems.org, and publish the [release notes](https://github.com/guard/guard/releases) .
 
 ### Author
 
-[Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](http://twitter.com/thibaudgg))
+[Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](https://twitter.com/thibaudgg))
 
 ### Core Team
 
-* [Maher Sallam](https://github.com/Maher4Ever) ([@mahersalam](http://twitter.com/mahersalam))
-* [Michael Kessler](https://github.com/netzpirat) ([@netzpirat](http://twitter.com/netzpirat), [mksoft.ch](https://mksoft.ch))
-* [Rémy Coutable](https://github.com/rymai) ([@rymai](http://twitter.com/rymai), [rymai.me](http://rymai.me))
-* [Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](http://twitter.com/thibaudgg), [thibaud.me](http://thibaud.me/))
+* R.I.P. :broken_heart: [Michael Kessler](https://github.com/netzpirat).
+* [Rémy Coutable](https://github.com/rymai).
+* [Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](https://twitter.com/thibaudgg), [thibaud.gg](https://thibaud.gg/)).
 
 ### Contributors
 
-[https://github.com/guard/guard/contributors](https://github.com/guard/guard/contributors)
+[https://github.com/guard/guard/graphs/contributors](https://github.com/guard/guard/graphs/contributors)