Growl

The growl gem is compatible with all versions of Growl and uses a command line tool
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.

Libnotify

The 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:

group :developmentdogem'libnotify'end

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.

Emacs

Terminal Notifier

Runs on Mac OS X 10.8 only

The terminal notifier sends notifications to the OS X Notification Center.
The notification center doesn't support different icons for different message types, and it even shows only the icon
from Terminal.app.

To use terminal_notifier you have to add it to your Gemfile and run bundler:

group :developmentdogem'terminal_notifier'end

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 on GitHub or by searching for guard-
on RubyGems.

When you have found a Guard plugin of your interest, add it to your Gemfile:

group :developmentdogem'<guard-plugin-name>'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

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:

$ 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:

$ 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:

$ guard init

You can also specify the name of an installed plugin to only get that plugin template
in the generated Guardfile:

$ guard init <guard-name>

You can also specify the names of multiple plugins to only get those plugin templates
in the generated Guardfile:

$ 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:

$ 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:

$ guard init --bare
$ guard init -b # shortcut

Start

Just launch Guard inside your Ruby or Rails project with:

$ 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:

$ guard --clear
$ guard -c # shortcut

-n/--notify option

System notifications 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.

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:

> rspec

It's also possible to run all plugins within a group by entering the group name:

> frontend

The same applies to reloading. You can reload a plugin with the following command:

> ronn reload

This will reload only the Ronn plugin. You can also reload all plugins within a group:

> backend reload

The action and plugin/group name can have any order, so you can also write:

> reload backend

You can pass a list of filenames to the change command to trigger manually a file modification:

> 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 on Mac OS X by default. You can
work around the issue by installing a pure Ruby implementation:

platforms :rubydogem'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 based interactor, which uses the new
io/console from stdlib. Just add it to your Gemfile

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

$ kill -USR1 <guard_pid>

Continue watching

$ 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:

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.

You can also launch any arbitrary command in the supplied block:

guard :shelldo
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.

Groups to be run can be specified with the Guard DSL option --group (or -g):

$ guard -g specs

Guard plugins that don't belong to a group are considered global and are always run.

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:

notification :growl

will select the growl gem for notifications. You can also set options for a notifier:

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:

notification :off

interactor

You can disable the interactor auto detection and select a specific implementation:

interactor :coolline
interactor :readline
interactor :simple

If you do not need the keyboard interactions with Guard at all, you can turn them off:

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.

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.

Please note that method only accept regexps. More on the
Listen README.

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.