guard 0.8.1 → 0.8.2

data/LICENSE

@@ -1,20 +1,20 @@
-Copyright (c) 2011 Thibaud Guillaume-Gentil
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+Copyright (c) 2011 Thibaud Guillaume-Gentil
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,434 +1,431 @@
-Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png)](http://travis-ci.org/guard/guard)
-=====
-
-Guard is a command line tool that easily handle events on files modifications.
-
-If you have any questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
-
-Features
---------
-
-* [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support on Mac OS X 10.5+ (without RubyCocoa!, [rb-fsevent gem, >= 0.3.5](https://rubygems.org/gems/rb-fsevent) required).
-* [Inotify](http://en.wikipedia.org/wiki/Inotify) support on Linux ([rb-inotify gem, >= 0.5.1](https://rubygems.org/gems/rb-inotify) required).
-* [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support on Windows ([rb-fchange, >= 0.0.2](https://rubygems.org/gems/rb-fchange) required).
-* Polling on the other operating systems (help us to support more OS).
-* Automatic & Super fast (when polling is not used) files modifications detection (even new files are detected).
-* Visual notifications on Mac OSX ([Growl](http://growl.info)), Linux ([Libnotify](http://developer.gnome.org/libnotify)) and Windows ([Notifu](http://www.paralint.com/projects/notifu)).
-* Tested against Ruby 1.8.7, 1.9.2, REE and the latest versions of JRuby & Rubinius.
-
-Screencast
-----------
-
-Ryan Bates made a Railscast on Guard, you can view it here: http://railscasts.com/episodes/264-guard
-
-Install
--------
-
-Install the gem:
-
-    $ gem install guard
-
-Or add it to your Gemfile (inside the `development` group):
-
-    gem 'guard'
-
-and install it via Bundler:
-
-    $ bundle install
-
-Generate an empty Guardfile with:
-
-    $ guard init
-
-You may optionally place a .Guardfile in your home directory to use it across multiple projects.
-Also note that if a `.guard.rb` is found in your home directory, it will be appended to the Guardfile.
-
-Add the guards you need to your Guardfile (see the existing guards below).
-
-### On Mac OS X
-
-Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
-
-    $ gem install rb-fsevent
-
-You have two possibilities:
-
-Use the [growl_notify gem](https://rubygems.org/gems/growl_notify) (recommended):
-
-    $ gem install growl_notify
-
-Use the [growlnotify](http://growl.info/extras.php#growlnotify) (cli tool for growl) + the [growl gem](https://rubygems.org/gems/growl).
-
-    $ brew install growlnotify
-    $ gem install growl
-
-And add them to your Gemfile:
-
-    gem 'rb-fsevent'
-    gem 'growl_notify' # or gem 'growl'
-
-The difference between growl and growl_notify is that growl_notify uses AppleScript to
-display a message, whereas growl uses the `growlnotify` command. In general the AppleScript
-approach is preferred, but you may also use the older growl gem. Have a look at the
-[Guard Wiki](https://github.com/guard/guard/wiki/Use-growl_notify-or-growl-gem) for more information.
-
-### On Linux
-
-Install the [rb-inotify gem](https://rubygems.org/gems/rb-inotify) for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
-
-    $ gem install rb-inotify
-
-Install the [libnotify gem](https://rubygems.org/gems/libnotify) if you want visual notification support:
-
-    $ gem install libnotify
-
-And add them to your Gemfile:
-
-    gem 'rb-inotify'
-    gem 'libnotify'
-
-### On Windows
-
-Install the [rb-fchange gem](https://rubygems.org/gems/rb-fchange) for [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support:
-
-    $ gem install rb-fchange
-
-Install the [win32console gem](https://rubygems.org/gems/win32console) if you want colors in your terminal:
-
-    $ gem install win32console
-
-Install the [rb-notifu gem](https://rubygems.org/gems/rb-notifu) if you want visual notification support:
-
-    $ gem install rb-notifu
-
-And add them to your Gemfile:
-
-    gem 'rb-fchange'
-    gem 'rb-notifu'
-    gem 'win32console'
-
-Usage
------
-
-Just launch Guard inside your Ruby / Rails project with:
-
-    $ guard [start]
-
-or if you use Bundler, to run the Guard executable specific to your bundle:
-
-    $ bundle exec guard [start]
-
-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.
-
-Command line options
---------------------
-
-### `-c`/`--clear` option
-
-Shell can be cleared after each change:
-
-    $ guard --clear
-    $ guard -c # shortcut
-
-### `-n`/`--notify` option
-
-Notifications (growl/libnotify) can be disabled:
-
-    $ 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 guards groups can be run (see the Guardfile DSL below for creating groups):
-
-    $ guard --group group_name another_group_name
-    $ guard -g group_name another_group_name # shortcut
-
-### `-d`/`--debug` option
-
-Guard can be run in debug mode:
-
-    $ guard --debug
-    $ guard -d # shortcut
-
-### `-w`/`--watchdir` option
-
-Guard can watch in any directory (instead of the current directory):
-
-    $ 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:
-
-    $ guard --guardfile ~/.your_global_guardfile
-    $ guard -G ~/.your_global_guardfile # shortcut
-
-### `-A`/`--watch-all-modifications` option
-
-Guard can optionally watch all file modifications like moves or deletions with:
-
-``` bash
-$ guard start -A
-$ guard start --watch-all-modifications
-```
-
-An exhaustive list of options is available with:
-
-    $ guard help [TASK]
-
-Interactions
-------------
-
-**From version >= 0.7.0 Posix Signal handlers are no more used to interact with Guard. If you're using a version < 0.7, please refer to the [README in the v0.6 branch](https://github.com/guard/guard/blob/v0.6/README.md).**
-
-When Guard do nothing you can interact with by entering a command + hitting enter:
-
-* `stop|quit|exit|s|q|e + enter` - Calls each guard's `#stop` method, in the same order they are declared in the Guardfile, and then quits Guard itself.
-* `reload|r|z + enter` - Calls each guard's `#reload` method, in the same order they are declared in the Guardfile.
-* `pause|p + enter` - Toggle files modification listening. Useful when switching git branches.
-* `just enter (no commands)` - Calls each guard's `#run_all` method, in the same order they are declared in the Guardfile.
-
-Available Guards
-----------------
-
-A list of the available guards is present [in the wiki](https://github.com/guard/guard/wiki/List-of-available-Guards).
-
-### Add a guard to your Guardfile
-
-Add it to your Gemfile (inside the `development` group):
-
-    gem '<guard-name>'
-
-You can list all guards installed on your system with:
-
-    $ guard list
-
-Insert default guard's definition to your Guardfile by running this command:
-
-    $ guard init <guard-name>
-
-You are good to go, or you can modify your guards' definition to suit your needs.
-
-Guardfile DSL
--------------
-
-The Guardfile DSL consists of the following methods:
-
-* `#guard`: allows you to add a guard with an optional hash of options.
-* `#watch`: allows you to define which files are supervised by this guard. An optional block can be added to overwrite the paths sent to the guard's `#run_on_change` method or to launch any arbitrary command.
-* `#group`: allows you to group several guards together. Groups to be run can be specified with the Guard DSL option `--group` (or `-g`). This comes in handy especially when you have a huge Guardfile and want to focus your development on a certain part. Guards that don't belong to a group are considered global and are always run.
-* `#callback`: allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`, `run_all` and `run_on_change` guards' method. You can even insert more hooks inside these methods. Please [checkout the Wiki page](https://github.com/guard/guard/wiki/Hooks-and-callbacks) for more details.
-* `#ignore_paths`: allows you to ignore top level directories altogether.  This comes is handy when you have large amounts of non-source data in you project.  By default .bundle, .git, log, tmp, and vendor are ignored.  Currently it is only possible to ignore the immediate descendants of the watched directory.
-
-Example:
-
-    ignore_paths 'foo', 'bar'
-
-    group 'backend' do
-      guard 'bundler' do
-        watch('Gemfile')
-      end
-
-      guard 'rspec', :cli => '--color --format doc' do
-        # Regexp watch patterns are matched with Regexp#match
-        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` }
-
-        # String watch patterns are matched with simple '=='
-        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
-
-Using a Guardfile without the `guard` binary
---------------------------------------------
-
-The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
-Available options are as follow:
-
-* `:guardfile`          - The path to a valid Guardfile.
-* `:guardfile_contents` - A string representing the content of a valid Guardfile
-
-Remember, without any options given, Guard will look for a Guardfile in your current directory and if it does not find one, it will look for it in your `$HOME` directory.
-
-For instance, you could use it as follow:
-
-    gem 'guard'
-    require 'guard'
-
-    Guard.setup
-
-    Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
-    # or
-    Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
-      guard 'rspec' do
-        watch(%r{^spec/.+_spec\.rb$})
-      end
-    ")
-
-### Listing defined guards/groups for the current project
-
-You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
-
-    $ guard -T
-
-    (global):
-      shell
-    Group backend:
-      bundler
-      rspec: cli => "--color --format doc"
-    Group frontend:
-      coffeescript: output => "public/javascripts/compiled"
-      livereload
-
-User config file
-----------------
-
-If a `.guard.rb` is found in your home directory, it will be appended to
-the Guardfile.  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):
-
-    guard 'shell' do
-      watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
-    end
-
-Create a new guard
-------------------
-
-Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
-
-    .travis.yml  # bonus point!
-    CHANGELOG.md # bonus point!
-    Gemfile
-    guard-name.gemspec
-    Guardfile
-    lib/
-      guard/
-        guard-name/
-          templates/
-            Guardfile # needed for `guard init <guard-name>`
-          version.rb
-        guard-name.rb
-    test/ # or spec/
-    README.md
-
-`Guard::GuardName` (in `lib/guard/guard-name.rb`) must inherit from `Guard::Guard` and should overwrite at least one of the five basic `Guard::Guard` instance methods.
-
-Here is an example scaffold for `lib/guard/guard-name.rb`:
-
-    require 'guard'
-    require 'guard/guard'
-
-    module Guard
-      class GuardName < Guard
-
-        def initialize(watchers = [], options = {})
-          super
-          # init stuff here, thx!
-        end
-
-        # =================
-        # = Guard methods =
-        # =================
-
-        # If one of those methods raise an exception, the Guard::GuardName instance
-        # will be removed from the active guards.
-
-        # Called once when Guard starts
-        # Please override initialize method to init stuff
-        def start
-          true
-        end
-
-        # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits)
-        def stop
-          true
-        end
-
-        # Called when `reload|r|z + enter` is pressed
-        # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
-        def reload
-          true
-        end
-
-        # Called when just `enter` is pressed
-        # This method should be principally used for long action like running all specs/tests/...
-        def run_all
-          true
-        end
-
-        # Called on file(s) modifications
-        def run_on_change(paths)
-          true
-        end
-
-        # Called on file(s) deletions
-        def run_on_deletion(paths)
-          true
-        end
-
-      end
-    end
-
-Please take a look at the [existing guards' source code](https://github.com/guard/guard/wiki/List-of-available-Guards) for more concrete example and inspiration.
-
-Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
-
-    require 'guard/guard'
-
-    module ::Guard
-      class InlineGuard < ::Guard::Guard
-        def run_all
-          true
-        end
-
-        def run_on_change(paths)
-          true
-        end
-      end
-    end
-
-Here is a very cool example by [@avdi](https://github.com/avdi) : http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis
-
-Development
------------
-
-* Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
-* Source hosted at [GitHub](https://github.com/guard/guard).
-* Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
-
-Pull requests are very welcome! Please try to follow these simple "rules", though:
-
-- Please create a topic branch for every separate change you make;
-- Make sure your patches are well tested;
-- Update the README (if applicable);
-- Update the CHANGELOG (maybe not for a typo but don't hesitate!);
-- Please **do not change** the version number.
-
-For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
-
-Author
-------
-
-[Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
-
-Contributors
-------------
-
-https://github.com/guard/guard/contributors
+Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png)](http://travis-ci.org/guard/guard)
+=====
+
+Guard is a command line tool that easily handle events on files modifications.
+
+If you have any questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
+
+Features
+--------
+
+* [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support on Mac OS X 10.5+ (without RubyCocoa!, [rb-fsevent gem, >= 0.3.5](https://rubygems.org/gems/rb-fsevent) required).
+* [Inotify](http://en.wikipedia.org/wiki/Inotify) support on Linux ([rb-inotify gem, >= 0.5.1](https://rubygems.org/gems/rb-inotify) required).
+* [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support on Windows ([rb-fchange, >= 0.0.2](https://rubygems.org/gems/rb-fchange) required).
+* Polling on the other operating systems (help us to support more OS).
+* Automatic & Super fast (when polling is not used) files modifications detection (even new files are detected).
+* Visual notifications on Mac OSX ([Growl](http://growl.info)), Linux ([Libnotify](http://developer.gnome.org/libnotify)) and Windows ([Notifu](http://www.paralint.com/projects/notifu)).
+* Tested against Ruby 1.8.7, 1.9.2, REE and the latest versions of JRuby & Rubinius.
+
+Screencast
+----------
+
+Ryan Bates made a Railscast on Guard, you can view it here: http://railscasts.com/episodes/264-guard
+
+Install
+-------
+
+Install the gem:
+
+    $ gem install guard
+
+Or add it to your Gemfile (inside the `development` group):
+
+    gem 'guard'
+
+and install it via Bundler:
+
+    $ bundle install
+
+Generate an empty Guardfile with:
+
+    $ guard init
+
+You may optionally place a .Guardfile in your home directory to use it across multiple projects.
+Also note that if a `.guard.rb` is found in your home directory, it will be appended to the Guardfile.
+
+Add the guards you need to your Guardfile (see the existing guards below).
+
+### On Mac OS X
+
+Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
+
+    $ gem install rb-fsevent
+
+You have two possibilities:
+
+Use the [growl_notify gem](https://rubygems.org/gems/growl_notify) (recommended):
+
+    $ gem install growl_notify
+
+Use the [growlnotify](http://growl.info/extras.php#growlnotify) (cli tool for growl) + the [growl gem](https://rubygems.org/gems/growl).
+
+    $ brew install growlnotify
+    $ gem install growl
+
+And add them to your Gemfile:
+
+    gem 'rb-fsevent'
+    gem 'growl_notify' # or gem 'growl'
+
+The difference between growl and growl_notify is that growl_notify uses AppleScript to
+display a message, whereas growl uses the `growlnotify` command. In general the AppleScript
+approach is preferred, but you may also use the older growl gem. Have a look at the
+[Guard Wiki](https://github.com/guard/guard/wiki/Use-growl_notify-or-growl-gem) for more information.
+
+### On Linux
+
+Install the [rb-inotify gem](https://rubygems.org/gems/rb-inotify) for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
+
+    $ gem install rb-inotify
+
+Install the [libnotify gem](https://rubygems.org/gems/libnotify) if you want visual notification support:
+
+    $ gem install libnotify
+
+And add them to your Gemfile:
+
+    gem 'rb-inotify'
+    gem 'libnotify'
+
+### On Windows
+
+Install the [rb-fchange gem](https://rubygems.org/gems/rb-fchange) for [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support:
+
+    $ gem install rb-fchange
+
+Install the [win32console gem](https://rubygems.org/gems/win32console) if you want colors in your terminal:
+
+    $ gem install win32console
+
+Install the [rb-notifu gem](https://rubygems.org/gems/rb-notifu) if you want visual notification support:
+
+    $ gem install rb-notifu
+
+And add them to your Gemfile:
+
+    gem 'rb-fchange'
+    gem 'rb-notifu'
+    gem 'win32console'
+
+Usage
+-----
+
+Just launch Guard inside your Ruby / Rails project with:
+
+    $ guard [start]
+
+or if you use Bundler, to run the Guard executable specific to your bundle:
+
+    $ bundle exec guard [start]
+
+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.
+
+Command line options
+--------------------
+
+### `-c`/`--clear` option
+
+Shell can be cleared after each change:
+
+    $ guard --clear
+    $ guard -c # shortcut
+
+### `-n`/`--notify` option
+
+Notifications (growl/libnotify) can be disabled:
+
+    $ 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 guards groups can be run (see the Guardfile DSL below for creating groups):
+
+    $ guard --group group_name another_group_name
+    $ guard -g group_name another_group_name # shortcut
+
+### `-d`/`--debug` option
+
+Guard can be run in debug mode:
+
+    $ guard --debug
+    $ guard -d # shortcut
+
+### `-w`/`--watchdir` option
+
+Guard can watch in any directory (instead of the current directory):
+
+    $ 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:
+
+    $ guard --guardfile ~/.your_global_guardfile
+    $ guard -G ~/.your_global_guardfile # shortcut
+
+### `-A`/`--watch-all-modifications` option
+
+Guard can optionally watch all file modifications like moves or deletions with:
+
+``` bash
+$ guard start -A
+$ guard start --watch-all-modifications
+```
+
+An exhaustive list of options is available with:
+
+    $ guard help [TASK]
+
+Interactions
+------------
+
+**From version >= 0.7.0 Posix Signal handlers are no more used to interact with Guard. If you're using a version < 0.7, please refer to the [README in the v0.6 branch](https://github.com/guard/guard/blob/v0.6/README.md).**
+
+When Guard do nothing you can interact with by entering a command + hitting enter:
+
+* `stop|quit|exit|s|q|e + enter` - Calls each guard's `#stop` method, in the same order they are declared in the Guardfile, and then quits Guard itself.
+* `reload|r|z + enter` - Calls each guard's `#reload` method, in the same order they are declared in the Guardfile.
+* `pause|p + enter` - Toggle files modification listening. Useful when switching git branches.
+* `just enter (no commands)` - Calls each guard's `#run_all` method, in the same order they are declared in the Guardfile.
+
+Available Guards
+----------------
+
+A list of the available guards is present [in the wiki](https://github.com/guard/guard/wiki/List-of-available-Guards).
+
+### Add a guard to your Guardfile
+
+Add it to your Gemfile (inside the `development` group):
+
+    gem '<guard-name>'
+
+You can list all guards installed on your system with:
+
+    $ guard list
+
+Insert default guard's definition to your Guardfile by running this command:
+
+    $ guard init <guard-name>
+
+You are good to go, or you can modify your guards' definition to suit your needs.
+
+Guardfile DSL
+-------------
+
+The Guardfile DSL consists of the following methods:
+
+* `#guard`: allows you to add a guard with an optional hash of options.
+* `#watch`: allows you to define which files are supervised by this guard. An optional block can be added to overwrite the paths sent to the guard's `#run_on_change` method or to launch any arbitrary command.
+* `#group`: allows you to group several guards together. Groups to be run can be specified with the Guard DSL option `--group` (or `-g`). This comes in handy especially when you have a huge Guardfile and want to focus your development on a certain part. Guards that don't belong to a group are considered global and are always run.
+* `#callback`: allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`, `run_all` and `run_on_change` guards' method. You can even insert more hooks inside these methods. Please [checkout the Wiki page](https://github.com/guard/guard/wiki/Hooks-and-callbacks) for more details.
+* `#ignore_paths`: allows you to ignore top level directories altogether.  This comes is handy when you have large amounts of non-source data in you project.  By default .bundle, .git, log, tmp, and vendor are ignored.  Currently it is only possible to ignore the immediate descendants of the watched directory.
+
+Example:
+
+    ignore_paths 'foo', 'bar'
+
+    group 'backend' do
+      guard 'bundler' do
+        watch('Gemfile')
+      end
+
+      guard 'rspec', :cli => '--color --format doc' do
+        # Regexp watch patterns are matched with Regexp#match
+        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` }
+
+        # String watch patterns are matched with simple '=='
+        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
+
+Using a Guardfile without the `guard` binary
+--------------------------------------------
+
+The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
+Available options are as follow:
+
+* `:guardfile`          - The path to a valid Guardfile.
+* `:guardfile_contents` - A string representing the content of a valid Guardfile
+
+Remember, without any options given, Guard will look for a Guardfile in your current directory and if it does not find one, it will look for it in your `$HOME` directory.
+
+For instance, you could use it as follow:
+
+    gem 'guard'
+    require 'guard'
+
+    Guard.setup
+
+    Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
+    # or
+    Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
+      guard 'rspec' do
+        watch(%r{^spec/.+_spec\.rb$})
+      end
+    ")
+
+### Listing defined guards/groups for the current project
+
+You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
+
+    $ guard -T
+
+    (global):
+      shell
+    Group backend:
+      bundler
+      rspec: cli => "--color --format doc"
+    Group frontend:
+      coffeescript: output => "public/javascripts/compiled"
+      livereload
+
+User config file
+----------------
+
+If a `.guard.rb` is found in your home directory, it will be appended to
+the Guardfile.  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):
+
+    guard 'shell' do
+      watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
+    end
+
+Create a new guard
+------------------
+
+Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
+
+    .travis.yml  # bonus point!
+    CHANGELOG.md # bonus point!
+    Gemfile
+    guard-name.gemspec
+    Guardfile
+    lib/
+      guard/
+        guard-name/
+          templates/
+            Guardfile # needed for `guard init <guard-name>`
+          version.rb
+        guard-name.rb
+    test/ # or spec/
+    README.md
+
+`Guard::GuardName` (in `lib/guard/guard-name.rb`) must inherit from
+[Guard::Guard](http://rubydoc.info/github/guard/guard/master/Guard/Guard) and should overwrite at least one of
+the basic `Guard::Guard` task methods.
+
+Here is an example scaffold for `lib/guard/guard-name.rb`:
+
+    require 'guard'
+    require 'guard/guard'
+
+    module Guard
+      class GuardName < Guard
+
+        # Initialize a Guard.
+        # @param [Array<Guard::Watcher>] watchers the Guard file watchers
+        # @param [Hash] options the custom Guard options
+        def initialize(watchers = [], options = {})
+          super
+        end
+
+        # Call once when Guard starts. Please override initialize method to init stuff.
+        # @raise [:task_has_failed] when start has failed
+        def start
+        end
+
+        # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
+        # @raise [:task_has_failed] when stop has failed
+        def stop
+        end
+
+        # Called when `reload|r|z + enter` is pressed.
+        # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
+        # @raise [:task_has_failed] when reload has failed
+        def reload
+        end
+
+        # Called when just `enter` is pressed
+        # This method should be principally used for long action like running all specs/tests/...
+        # @raise [:task_has_failed] when run_all has failed
+        def run_all
+        end
+
+        # Called on file(s) modifications that the Guard watches.
+        # @param [Array<String>] paths the changes files or paths
+        # @raise [:task_has_failed] when run_on_change has failed
+        def run_on_change(paths)
+        end
+
+        # Called on file(s) deletions that the Guard watches.
+        # @param [Array<String>] paths the deleted files or paths
+        # @raise [:task_has_failed] when run_on_change has failed
+        def run_on_deletion(paths)
+        end
+
+      end
+    end
+
+Please take a look at the [existing guards' source code](https://github.com/guard/guard/wiki/List-of-available-Guards)
+for more concrete example and inspiration.
+
+Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
+
+    require 'guard/guard'
+
+    module ::Guard
+      class InlineGuard < ::Guard::Guard
+        def run_all
+        end
+
+        def run_on_change(paths)
+        end
+      end
+    end
+
+Here is a very cool example by [@avdi](https://github.com/avdi) : http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis
+
+Development
+-----------
+
+* Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
+* Source hosted at [GitHub](https://github.com/guard/guard).
+* Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
+
+Pull requests are very welcome! Please try to follow these simple "rules", though:
+
+- Please create a topic branch for every separate change you make;
+- Make sure your patches are well tested;
+- Update the README (if applicable);
+- Update the CHANGELOG (maybe not for a typo but don't hesitate!);
+- Please **do not change** the version number.
+
+For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
+
+Author
+------
+
+[Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
+
+Contributors
+------------
+
+https://github.com/guard/guard/contributors