Guard is a command line tool to easily handle events on file system modifications.

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 or on #guard (irc.freenode.net).

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.

Before you file an issue, make sure you have read the file an issue section that contains some important information.

• File system changes handled by our awesome Listen gem.
• Support for visual system notifications.
• Huge eco-system with more than 130 guard plugins.
• Tested against Ruby 1.8.7, 1.9.2, 1.9.3, REE and the latest versions of JRuby & Rubinius.

Ryan Bates made an excellent RailsCast about Guard and you should definitely watch it for a nice introduction to Guard.

The simplest way to install Guard is to use Bundler.

Add Guard to your Gemfile:

group :development do
  gem 'guard'
end

and install it by running Bundler:

$ bundle

Generate an empty Guardfile with:

$ guard init

If you are using Windows and want colors in your terminal, you'll have to add the win32console gem to your Gemfile and install it with Bundler:

group :development do
  gem 'win32console'
end

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.

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:

• Runs on Mac OS X
• Supports all Growl versions

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.

You have to download the installer for growlnotify from the Growl download section.

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

group :development do
  gem 'growl'
end

There's currently a bug in Growl that prevents displaying the icons through GNTP, see issue #231. Use the growl gem until fixed.

• Runs on Mac OS X, Linux and Windows
• Supports Growl version >= 1.3, Growl for Linux, Growl for Windows and Snarl

The ruby_gntp gem sends system notifications over the network with the Growl Notification Transport Protocol and supports local and remote notifications.

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.

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

group :development do
  gem 'ruby_gntp'
end

• Runs on Linux, FreeBSD, OpenBSD and Solaris
• Supports 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 :development do
  gem '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.

• Runs on Windows
• Supports Notifu

The rb-notifu gem supports Windows system tray notifications.

To use rb-notifu you have to add it to your Gemfile and run bundler:

group :development do
  gem 'rb-notifu'
end

• Runs on Mac OS X
• Supports Growl version >= 1.3
• Doesn't support JRuby and MacRuby.
• Doesn't work when forking, e.g. with Spork.

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

Guard supports multiple notification channels for customizing each notification type and you need to have at least Growl version 1.3 installed.

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

group :development do
  gem 'growl_notify'
end

• Runs on any platform with Emacs + emacsclient (http://www.emacswiki.org/emacs/EmacsClient)

• Runs on Mac OS X 10.8 only

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

group :development do
  gem 'terminal-notifier-guard'
end

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 :development do
  gem '<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.

Guard is run from the command line. Please open your terminal and go to your project work directory.

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

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.

You can generate an empty Guardfile by running the init task with the bare option:

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

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.

The shell can be cleared after each change:

$ guard --clear
$ guard -c # shortcut

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.

Only certain plugin groups can be run:

$ guard --group group_name another_group_name
$ guard -g group_name another_group_name # shortcut

See the Guardfile DSL below for creating groups.

Guard can display debug information which can be very usefull for plugins developers with:

$ guard --debug
$ guard -d # shortcut

Guard can watch any directory instead of the current directory:

$ guard --watchdir ~/your/fancy/project
$ guard -w ~/your/fancy/project # shortcut

Guard can use a Guardfile not located in the current directory:

$ guard --guardfile ~/.your_global_guardfile
$ guard -G ~/.your_global_guardfile # shortcut

Turn off completely any Guard terminal interactions with:

$ guard start -i
$ guard start --no-interactions

Skip Bundler warning when a Gemfile exists in the project directory but Guard is not run with Bundler.

$ guard start -B
$ guard start --no-bundler-warning

Overwrite Listen's default latency, useful when your hard-drive / system is slow.

$ guard start -l 1.5
$ guard start --latency 1.5

Force Listen polling listener usage.

$ guard start -p
$ guard start --force-polling

You can list the available plugins with the list task:

$ 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

You can show the structure of the groups and their plugins with the show task:

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

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

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

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.

You can also interact with Guard by sending POSIX signals to the Guard process (all but Windows and JRuby).

$ kill -USR1 <guard_pid>

$ kill -USR2 <guard_pid>

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:

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:

guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'

You can define the same plugin more than once:

guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'
guard :coffeescript, :input => 'specs', :output => 'specs'

The watch method allows you to define which files are watched by a Guard:

guard :bundler do
  watch('Gemfile')
end

String watch patterns are matched with String#==. You can also pass a regular expression to the watch method:

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.

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:

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.

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

guard :shell do
  watch('.*') { `git status` }
end

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.

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

$ guard -g specs

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

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:

notification :growl, :sticky => true

Each notifier has a slightly different set of supported options:

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:

notification :off

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

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.

guard :rspec do
  watch(%r{^spec/.+_spec\.rb$})

  callback(:start_begin) { `mate .` }
end

Please see the hooks and callbacks page in the Guard wiki for more details.

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 are ignored.

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

ignore %r{^ignored/path/}, /public/

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.

filter /\.txt$/, /.*\.zip/

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

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:

guard :shell do
  watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
end

You can report bugs and feature requests to GitHub Issues.

Please don't ask question in the issue tracker, instead ask them in our Google group or on #guard (irc.freenode.net).

Try to figure out where the issue belongs to: Is it an issue with Guard itself or with a Guard plugin you're using?

When you file a bug, please try to follow these simple rules if applicable:

• 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.

It's most likely that your bug gets resolved faster if you provide as much information as possible!

• Documentation hosted at RubyDoc.
• Source hosted at GitHub.

Pull requests are very welcome! Please try to follow these simple rules if applicable:

• 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 documentation.
• Update the README.
• Update the CHANGELOG for noteworthy changes.
• Please do not change the version number.

For questions please join us in our Google group or on #guard (irc.freenode.net).

Thibaud Guillaume-Gentil (@thibaudgg)

• Maher Sallam (@mahersalam)
• Michael Kessler (@netzpirat, mksoft.ch)
• Rémy Coutable (@rymai, rymai.me)
• Thibaud Guillaume-Gentil (@thibaudgg, thibaud.me)

https://github.com/guard/guard/contributors