kewubenduben/guard

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

⚠️ Guard is looking for new maintainers. Please contact me if you're interested.

Guard

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

Guard has many very handy features, so read this document through at least once to be aware of them - or you'll likely miss out on really cool ideas and tricks.

Also, by reading through you'll likely avoid common and time-consuming problems which Guard simply can't automatically solve.

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 220 Guard plugins.
• Tested against Ruby 1.9.3, 2.0.0, 2.1.0, JRuby & Rubinius.

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 Mac OS X.

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 guard will create bin/guard in your project, which means running bin/guard (tab completion will save you a key stroke or two) will have the exact same result as bundle exec guard

• Or, for RubyGems >= 2.2.0 (at least, though the more recent the better), simply set the RUBYGEMS_GEMDEPS environment 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 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.

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

• R.I.P. 💔 Michael Kessler (@netzpirat, flinkfinger.com)
• Rémy Coutable
• Thibaud Guillaume-Gentil (@thibaudgg, thibaud.gg)

Contributors

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