This document contains a lot of information, please take your time and read these instructions carefully. If you have any questions about the Guard usage or want to share some information with the Guard community, please go to one of the following places:
- Google+ community
- Google group
- StackOverflow
- IRC channel
#guard
(irc.freenode.net) for chatting
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 known issues and file an issue sections that contains some important information.
Features
- File system changes handled by our awesome Listen gem.
- Support for visual system notifications.
- Huge eco-system with more than 190 guard plugins.
- Tested against Ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0, REE and the latest versions of JRuby & Rubinius.
Screencast
Two nice introduction screen casts to Guard are available that helps you get started:
- Guard is Your Best Friend on Net Tuts+
- Guard on RailsCast
Installation
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
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.
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 Mac OS X.
Windows Colors
If you 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
Interrupt handling
If the Pry interactor is used, then Ctrl-C
is delegated to Pry to exit continuation and Ctrl-D
to exit Guard.
Without interactor, Ctrl-C
exits Guard and Ctrl-D
is ignored.
System notifications
You can configure Guard to notify plugin results throgh one or more channels described below. If you do not specify a specific notification channel with the notification DSL method, then Guard auto-detects all available channels and makes use of them.
Ruby GNTP
- 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. To have the images be displayed, you have to use 127.0.0.1
instead of localhost
in your GTNP
configuration.
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
Growl
- 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
Libnotify
- 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
.
Notifu
- 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
GrowlNotify
- 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
Terminal Notifier
- 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
Terminal Title
- Runs in every terminal supporting XTerm escape sequences to set the window title.
Emacs
- Runs on any platform with Emacs + emacsclient (http://www.emacswiki.org/emacs/EmacsClient)
TMux
- To use TMux notifications, you have to start Guard within a TMux session.
The TMux notifier will color the background of the left part of the
status bar indicating the status of the notifications. Optionally you
can set :display_message => true
to display the Guard notification as
'display-message' notification.
The way these messages are formatted is configurable.
# Guardfile
notification :tmux,
:display_message => true,
:timeout => 5, # in seconds
:default_message_format => '%s >> %s',
# the first %s will show the title, the second the message
# Alternately you can also configure *success_message_format*,
# *pending_message_format*, *failed_message_format*
:line_separator => ' > ', # since we are single line we need a separator
:color_location => 'status-left-bg' # to customize which tmux element will change color
The result will be for RSpec using example above
RSpec >> 15 test, 0 failures > in 0.002 sec
You can use nice powerline chars here if you have that configured.
You can get the message history by using Ctrl+b ~
(where Ctrl+b
is your key to activate TMux).
File
- You can also have Guard write notifications to a file. Each notification will overwrite the file. This allows other commands to be run based on the status of other guard commands.
Example:
# Guardfile
notification :file, path: '.guard_result'
guard :shell do
watch '.guard_result' do
if File.read('.guard_result').lines.first.strip == 'failed'
# ...
end
end
end
Configuration:
# Guardfile
notification :file,
:path => '.guard_result', # Required, no default
:format => "result: %s\ntitle: %s\nmessage: %s\n" # Default: "%s\n%s\n%s\n"
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 :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.
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
You can add the following snippet to your ~/.guardrc
to have the clear option always be enabled:
Guard.options[:clear] = true
-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
.
-g
/--group
option
Scope Guard to certain plugin groups on start:
$ guard --group group_name another_group_name
$ guard -g group_name another_group_name # shortcut
See the Guardfile DSL below for creating groups.
-P
/--plugins
option
Scope Guard to certain plugins on start:
$ guard --plugins plugin_name another_plugin_name
$ guard -P plugin_name another_plugin_name # shortcut
-d
/--debug
option
Guard can display debug information which can be very usefull for plugins developers with:
$ guard --debug
$ guard -d # shortcut
-w
/--watchdir
option
Guard can watch 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
-i
/--no-interactions
option
Turn off completely any Guard terminal interactions with:
$ 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.
$ guard start -B
$ guard start --no-bundler-warning
-l
/--latency
option
Overwrite Listen's default latency, useful when your hard-drive / system is slow.
$ guard start -l 1.5
$ guard start --latency 1.5
-p
/--force-polling
option
Force Listen polling listener usage.
$ guard start -p
$ guard start --force-polling
List
You can list the available plugins with the list
task:
$ guard list
+----------+--------------+
| Plugin | In Guardfile |
+----------+--------------+
| Compass | ✘ |
| Cucumber | ✘ |
| Jammit | ✘ |
| Ronn | ✔ |
| Rspec | ✔ |
| Spork | ✘ |
| Yard | ✘ |
+----------+--------------+
Show
You can show the structure of the groups and their plugins with the show
task:
$ guard show
+---------+--------+-----------------+----------------------------+
| Group | Plugin | Option | Value |
+---------+--------+-----------------+----------------------------+
| Specs | Rspec | all_after_pass | true |
| | | all_on_start | true |
| | | cli | "--fail-fast --format doc" |
| | | focus_on_failed | false |
| | | keep_failed | true |
| | | run_all | {} |
| | | spec_paths | ["spec"] |
+---------+--------+-----------------+----------------------------+
| Docs | Ronn | | |
+---------+--------+-----------------+----------------------------+
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.
Interactions
Guard shows a Pry console whenever it has nothing to do and comes with some Guard specific Pry commands:
↩
,a
,all
: Run all plugins.h
,help
: Show help for all interactor commands.c
,change
: Trigger a file change.n
,notification
: Toggles the notifications.p
,pause
: Toggles the file listener.r
,reload
: Reload all plugins.o
,scope
: Scope Guard actions to plugins or groups.s
,show
: Show all Guard plugins.e
,exit
: Stop all plugins and quit Guard
The all
and reload
commands supports an optional scope, so you limit the Guard action to either a Guard plugin or
a Guard group like:
[1] guard(main)> all rspec
[2] guard(main)> all frontend
Remember, you can always use help
on the Pry command line to see all available commands and help <command>
for
more detailed information. help guard
will show all Guard related commands available
Pry supports the Ruby built-in Readline, rb-readline and Coolline. Just install the readline implementation of your choice by adding it to your `Gemfile.
You can also disable the interactions completely by running Guard with the --no-interactions
option.
Customizations
Further Guard specific customizations can be made in ~/.guardrc
that will be evaluated prior the Pry session is
started (~/.pryrc
is ignored). This allows you to make use of the Pry plugin architecture to provide custom commands
and extend Guard for your own needs and distribute as a gem. Please have a look at the
Pry Wiki for more information.
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:
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'
watch
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
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.
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.
Another neat use of groups is to group dependant plugins and stop processing if one fails. In order
to make this work, the group needs to have the halt_on_fail
option enabled and the Guard plugin
needs to throw :task_has_failed
to indicate that the action was not successful.
group :specs, :halt_on_fail => true do
guard :rspec do
watch(/.../)
end
guard :cucumber do
watch(/.../)
end
end
scope
The scope
method allows you to define the default plugin or group scope for Guard, if not
specified as command line option. Thus command line group and plugin scope takes precedence over
the DSL scope configuration.
You can define either a single plugin or group:
scope :plugin => :rspec
scope :group => :docs
or specify multiple plugins or groups.
scope :plugins => [:test, :jasmine]
scope :groups => [:docs, :frontend]
If you define both the plugin and group scope, the plugin scope has precedence. If you use both the plural and the singular option, the plural has precedence.
notification
If you don't specify any notification configuration in your Guardfile
, Guard goes through the list of available
notifiers and enables all that are 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
interactor
You can customize the Pry interactor history and RC file like:
interactor :guard_rc => '~/.my_guard-rc', :history_file => '~/.my_guard_history_file'
If you do not need the Pry interactions with Guard at all, you can turn it 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.
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.
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
are ignored.
Please note that method only accept regexps. More on the Listen README.
To append to the default ignored files and directories, use the ignore
method:
ignore %r{^ignored/path/}, /public/
To replace to default ignored files and directories, use the ignore!
method:
ignore! /data/
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.
filter /\.txt$/, /.*\.zip/
To replace any existing filter, use the filter!
method:
filter! /\.js$/
logger
The logger
method allows you to customize the Lumberjack log output to your
needs by specifying one or more options like:
logger :level => :warn,
:template => '[:severity - :time - :progname] :message',
:time_format => 'at %I:%M%p',
:only => [:rspec, :jasmine, 'coffeescript'],
:except => :jammit,
:device => 'guard.log'
Log :level
option must be either :debug
, :info
, :warn
or :error
. If Guard is started in debug mode, the log
level will be automatically set to :debug
.
The :template
option is a string which can have one or more of the following placeholders: :time
, :severity
,
:progname
, :pid
, :unit_of_work_id
and :message
. A unit of work is assigned for each action Guard performs on
multiple Guard plugin.
The :time_format
option directives are the same as Time#strftime or can be :milliseconds
The :only
and :except
are either a string or a symbol, or an array of strings or symbols that matches the name of
the Guard plugin name that sends the log message. They cannot be specified at the same time.
By default the logger uses $stderr
as device, but you can override this by supplying the :device
option and set
either an IO stream or a filename.
Example
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:
guard :shell do
watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
end
Known issues
Please check guard's GitHub issue tracker for known issues. Additionally you should check listen's issue tracker for issues which affect guard's behaviour; for example, there is currently a nasty bug preventing listen from watching files inside symlinked directories.
File an issue
You can report bugs and feature requests to GitHub Issues.
Please don't ask question in the issue tracker, instead ask them at one of our other places:
- Google+ community
- Google group
- StackOverflow
- IRC channel
#guard
(irc.freenode.net) for chatting
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've read the README carefully.
- 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
andGemfile
to the issue. - Provide information about your environment:
- Your current versions of your OS, Ruby, Rubygems and Bundler.
- Shared project folder with services like Dropbox, NFS, etc.
- 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!
Development
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 must pass on Travis CI.
- Update the Yard documentation.
- Update the README.
- Update the CHANGELOG for noteworthy changes (don't forget to run
bundle exec pimpmychangelog
and watch the magic happen)! - Please do not change the version number.
For questions please join us in our Google group or on
#guard
(irc.freenode.net).
Open Commit Bit
Guard has an open commit bit policy: Anyone with an accepted pull request gets added as a repository collaborator. Please try to follow these simple rules:
- Commit directly onto the master branch only for typos, improvements to the readme and documentation (please add
[ci skip]
to the commit message). - Create a feature branch and open a pull-request early for any new features to get feedback.
- Make sure you adhere to the general pull request rules above.
Author
Thibaud Guillaume-Gentil (@thibaudgg)
Core Team
- Maher Sallam (@mahersalam)
- Michael Kessler (@netzpirat, mksoft.ch)
- Rémy Coutable (@rymai, rymai.me)
- Thibaud Guillaume-Gentil (@thibaudgg, thibaud.me)