Since all dynamic elements in a statically generated site will require Javascript, users of static generators might appreciate javascript-specific features like combining scripts and minifying them. These features exist in Javascript build tools like Sprockets or Brunch and tool that adds these features to a static site builder may be exactly what is needed to build sites that are rich in both content and client-side functionality.
A complete build tool might seem like overkill when a make/fab/rake/cake file combined with something like guard to watch your files and rebuild during the development is all that's required. While this will certainly work, it's a nontrivial problem since rebuilding everything from scratch after every change is not feasible for sites with lots of content or scripts.
---------------------------------------------------
Guard
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 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
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 220 Guard plugins.
- Tested against Ruby 1.9.3, 2.0.0, JRuby (1.9 mode) & Rubinius (1.9 mode).
Screencast
Two nice screencasts are available to help you get started:- Guard on RailsCast.
- Guard is Your Best Friend on Net Tuts+.
Installation
The simplest way to install Guard is to use Bundler.Add Guard (and any other dependencies) to a
Gemfile
in your project’s root:group :development do
gem 'guard'
end
$ bundle
Guardfile
with:$ bundle exec guard init
$ bundle exec guard
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.
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 forguard-
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
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 thehelp
task:$ bundle exec guard help
start
task, simply run:$ bundle exec guard help start
Init
You can generate a Guardfile and have all installed plugins be automatically added into it by running theinit
task without any option:$ bundle exec guard init
$ bundle exec guard init <guard-name>
$ bundle exec guard init <guard1-name> <guard2-name>
~/.guard/templates/
which can be appended in the same way to your existing
Guardfile
:$ bundle exec guard init <template-name>
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:$ bundle exec guard init --bare
$ bundle exec guard init -b # shortcut
Start
Just launch Guard inside your Ruby or Rails project with:$ bundle exec guard
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:$ bundle exec guard --clear
$ bundle exec guard -c # shortcut
~/.guardrc
to have the clear option always be enabled:Guard.options[:clear] = true
-n
/--notify
option
System notifications can be disabled:$ bundle exec guard --notify false
$ bundle exec guard -n f # shortcut
GUARD_NOTIFY
environment variable to false
.
-g
/--group
option
Scope Guard to certain plugin groups on start:$ bundle exec guard --group group_name another_group_name
$ bundle exec guard -g group_name another_group_name # shortcut
-P
/--plugin
option
Scope Guard to certain plugins on start:$ bundle exec guard --plugin plugin_name another_plugin_name
$ bundle exec 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:$ bundle exec guard --debug
$ bundle exec guard -d # shortcut
-w
/--watchdir
option
Guard can watch any number of directories instead of only the current directory:$ bundle exec guard --watchdir ~/your/fancy/project
$ bundle exec guard -w ~/your/fancy/project ~/your/fancier/project2 #multiple directories
$ bundle exec guard -w ~/your/fancy/project # shortcut
-G
/--guardfile
option
Guard can use a Guardfile
not located in the current directory:$ bundle exec guard --guardfile ~/.your_global_guardfile
$ bundle exec guard -G ~/.your_global_guardfile # shortcut
-i
/--no-interactions
option
Turn off completely any Guard terminal interactions with:$ bundle exec guard start -i
$ bundle exec 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.$ bundle exec guard start -B
$ bundle exec guard start --no-bundler-warning
--show-deprecations
Turn on deprecation warnings.
-l
/--latency
option
Overwrite Listen's default latency, useful when your hard-drive / system is slow.$ bundle exec guard start -l 1.5
$ bundle exec guard start --latency 1.5
-p
/--force-polling
option
Force Listen polling listener usage.$ bundle exec guard start -p
$ bundle exec guard start --force-polling
-y
/--wait-for-delay
option
Overwrite Listen's default wait_for_delay, useful for kate-like editors through ssh access.$ bundle exec guard start -y 1
$ bundle exec guard start --wait-for-delay 1
List
You can list the available plugins with thelist
task:$ bundle exec 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 theshow
task:$ bundle exec 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 | | |
+---------+--------+-----------------+----------------------------+
Guardfile
or .Guardfile
, with the .guard.rb
file. You can
read more about these files in the shared configuration section.Notifiers
You can show the notifiers, their availablity and options with thenotifier
task:$ bundle exec guard notifiers
+-------------------+-----------+------+------------------------+-------------------+
| Name | Available | Used | Option | Value |
+-------------------+-----------+------+------------------------+-------------------+
| gntp | ✔ | ✘ | sticky | false |
+-------------------+-----------+------+------------------------+-------------------+
| growl | ✘ | ✘ | sticky | false |
| | | | priority | 0 |
+-------------------+-----------+------+------------------------+-------------------+
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
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
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 availablePry 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).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.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 yourGuardfile
.
Guard itself provides the following DSL methods that can be used for configuration:guard
Theguard
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'
guard :coffeescript, input: 'coffeescripts', output: 'javascripts'
guard :coffeescript, input: 'specs', output: 'specs'
watch
Thewatch
method allows you to define which files are watched by a Guard:guard :bundler do
watch('Gemfile')
end
guard :jessie do
watch(%r{^spec/.+(_spec|Spec)\.(js|coffee)})
end
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
(.+)
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
Thegroup
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
group :desktop do
guard 'livereload' do
watch(%r{desktop/.+\.html})
end
group :mobile do
guard 'livereload' do
watch(%r{mobile/.+\.html})
end
end
end
group :mobile, :desktop do
guard 'livereload' do
watch(%r{both/.+\.html})
end
end
--group
(or -g
):$ bundle exec guard -g specs
default
group.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
Thescope
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
scope plugins: [:test, :jasmine]
scope groups: [:docs, :frontend]
Please be sure to call the
scope
method after you've declared your Guard plugins!notification
If you don't specify any notification configuration in yourGuardfile
, 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
growl
gem for notifications. You can also set options for a notifier:notification :growl, sticky: true
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
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'
interactor :off
callback
Thecallback
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
ignore
Theignore
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
, .DS_Store
, .git
, .hg
,.svn
, bundle
, log
, tmp
, vendor/bundle
are ignored.Please note that method only accept regexps. See Listen README.
To append to the default ignored files and directories, use the
ignore
method:ignore %r{^ignored/path/}, /public/
ignore!
method:ignore! /data/
filter
Alias of the ignore method.logger
Thelogger
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'
: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.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
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.
Development
Pull requests are very welcome! Please try to follow these simple rules if applicable:from https://github.com/guard/guard