Guard
IMPORTANT: Please upgrade to Ruby >= 2.4 before installing Guard! To install for older versions, update Bundler at least 1.12: gem update bundler and Bundler should correctly resolve to earlier gems for your given Ruby version.
- Ruby 2.1 is officially outdated and unsupported!
- Ruby 2.2 is officially outdated and unsupported!
- Ruby 2.3 is officially outdated and unsupported!
:exclamation: Guard is currently accepting more maintainers. Please read this if you're interested in joining the team.
It's frequently used by software developers, web designers, writers and other specialists to avoid mundane, repetitive actions and commands such as "relaunching" tools after changing source files or configurations.
Common use cases include: an IDE replacement, web development tools, designing "smart" and "responsive" build systems/workflows, automating various project tasks and installing/monitoring various system services.
For a full categorized list of known Guard plugins, look here: https://github.com/guard/guard/wiki/Guard-Plugins
If you have
any questions about Guard or want to share some information with the Guard community, please go to one of
the following places:
- Guard Wiki
- 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 300 Guard plugins.
- Tested against the latest Ruby 2.4.x, 2.5.x, 2.6.x, JRuby & Rubinius. See
.travis-ci.ymlfor the exact versions.
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
then install it by running Bundler:
$ bundle
Generate an empty Guardfile with:
$ bundle exec guard init
Run Guard through Bundler with:
$ bundle exec guard
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 macOS.
Avoiding gem/dependency problems
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 one of the following:
-
(Recommended) Running
bundle binstub guardwill createbin/guardin your
project, which means runningbin/guard(tab completion will save you a key
stroke or two) will have the exact same result asbundle exec guard. -
Or, you can
alias be="bundle exec"in your.bashrcor similar and the execute onlybe guard.
Protip: It will work for all comands executed inbundle execcontext! -
Or, for RubyGems >= 2.2.0 (at least, though the more recent the better),
simply set theRUBYGEMS_GEMDEPSenvironment variable to-(for autodetecting
the Gemfile in the current or parent directories) or set it to the path of your Gemfile.
(To upgrade RubyGems from RVM, use the rvm rubygems command).
NOTE: this Rubygems feature is still under development still lacks many features of bundler
- Or, for RubyGems < 2.2.0 check out the Rubygems Bundler.
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.
Look here for a full list of Guard commands
Start
Just launch Guard inside your Ruby or Rails project with:
$ bundle exec guard
Guard will look for a Guardfile or guardfile.rb in your current directory. If it does not find one, it will look
in your $HOME directory for a .Guardfile.
Please look here to see all the command line options for Guard
Interactions
Please read how to interact with Guard on the console and which signals Guard accepts
Guardfile DSL
For details on extending your Guardfile look at Guardfile examples or look at a list of commands Guardfile-DSL / Configuring-Guard
Issues
Before reporting a problem, please read how to File an issue.
Development / Contributing
See the Contributing Guide.
Releasing
Prerequisites
- You must have commit rights to the GitHub repository.
- You must have push rights for rubygems.org.
How to release
- Determine which would be the correct next version number according to semver.
- Update the version in
./lib/guard/version.rb. - Commit the version in a single commit, the message should be "Bump VERSION to X.Y.Z".
- Push and open a pull request.
- Once CI is green, merge the pull request.
- Pull the changes locally and run
bundle exec rake release:full; this will tag, push to GitHub, publish to rubygems.org, and publish the release notes .
Author
Thibaud Guillaume-Gentil (@thibaudgg)
Core Team
- R.I.P. :broken_heart: Michael Kessler.
- Rémy Coutable.
- Thibaud Guillaume-Gentil (@thibaudgg, thibaud.gg).