Guard: automating file system tasks in Ruby projects

Automating repetitive tasks when source files change

Guard is a command-line tool that runs custom rules whenever files or directories change. It automates work that developers and designers repeat constantly: restarting a test runner when test files change, recompiling assets when styles change, running a linter after code edits, or rebuilding documentation when source comments change. Guard watches the file system through the Listen gem and fires rules based on patterns you define in a Guardfile. The tool is frequently used as an IDE replacement in projects that do not rely on a full IDE, by teams designing responsive build systems, and by anyone automating repetitive tasks that follow file changes. The ecosystem includes more than 300 Guard plugins, each adding task types. Some are for continuous testing (guard-rspec), some for asset compilation (guard-sass), and others for documentation (guard-yard). You can also write custom plugins for domain-specific workflows.

Setting up Guard with Bundler and Guardfile configuration

Guard installation begins with Bundler. Add Guard to your Gemfile in the development group:

group :development do
  gem 'guard'
end

Then run Bundler to install it:

$ bundle

Generate a basic Guardfile with Guard's initialization command:

$ bundle exec guard init

This creates an empty Guardfile in your project root that you can customize with rules. To start Guard, run:

$ bundle exec guard

Guard searches for a Guardfile or guardfile.rb in the current directory, then in your home directory for .Guardfile. The Bundler approach is important: running Guard through Bundler ensures that it uses the correct gem versions from your project's Gemfile. If you tire of typing `bundle exec` repeatedly, create a binstub with `bundle binstub guard`, which creates bin/guard in your project. After this, you can run `bin/guard` with the same result as `bundle exec guard`.

File system patterns and notifications

Guard watches directories based on patterns you define in the Guardfile. When a file matches a pattern, Guard triggers an action. The Guardfile uses a domain-specific language (DSL) to specify watchers and callbacks. The README links to Guardfile examples and documentation on the Guard wiki, but does not include a full syntax reference. Guard supports visual system notifications, showing status changes in your OS notification center. This visual feedback means you can keep Guard running in a terminal window without watching it constantly and still know when tests pass or fail. File system monitoring is handled by the Listen gem, which detects file changes through the OS file system API. Guard has been tested against Ruby 2.4.x, 2.5.x, 2.6.x, JRuby and Rubinius, ensuring broad platform compatibility for teams using different Ruby implementations. On macOS, if Guard fails to react to file changes or Pry (the interactive debugger) behaves strangely, the README recommends adding proper Readline support to Ruby on macOS, with a linked guide in the Guard wiki.

Avoiding dependency and bundling issues with Guard

The single most important rule with Guard is to always run it through Bundler. Running Guard directly against the system Ruby or an environment without Bundler creates version conflicts with other Ruby tools and plugins. If you find yourself constantly typing `bundle exec guard`, the recommended shortcut is to use `bundle binstub guard`, which creates an executable in your project at bin/guard. This approach is safer than setting an alias because it binds Guard to your project's specific Gemfile and gem versions. For older RubyGems versions (before 2.2.0), the README documents the Rubygems Bundler gem as an alternative. For RubyGems 2.2.0 and later, you can set the `RUBYGEMS_GEMDEPS` environment variable to `-` (meaning autodetect) or to the path of your Gemfile. The README notes that this Rubygems feature is still under development and lacks many features of Bundler, so Bundler itself is the supported approach.

Adding Guard plugins for your workflow

Once Guard is running, you add plugins to perform specific tasks. The Guard ecosystem includes more than 300 plugins available through the Guard organization on GitHub and the RubyGems package index (search for `guard-` to find them). When you find a plugin you need, add it to your Gemfile in the development group, the same as the base Guard gem. Each plugin documents how to configure it in the Guardfile. The plugin supplies a template that you run through `bundle exec guard init <plugin-name>` to generate starter configuration. You customize that template to match your project's structure and tools. For example, guard-rspec runs your test suite whenever you save a test file or application file; guard-sass recompiles CSS whenever a Sass file changes. This plugin-based architecture means Guard is extensible: if no existing plugin matches your need, you can write a custom Guard plugin for internal tools or workflows. A full categorized list of known Guard plugins is available on the Guard wiki for reference.

Interacting with Guard and handling signals

Guard accepts keyboard commands while running. The full list of Guard commands is documented on the Guard wiki under List of Guard Commands. You can also interact with Guard through signals sent from another terminal. The wiki's Interacting with Guard page documents which signals Guard accepts and how they affect its behavior. Common interactions include pausing Guard temporarily, reloading the Guardfile after making edits, or stopping Guard cleanly. These interactions are important when you are debugging a problem or need to change configuration without restarting the terminal window.

Guard vs. continuous integration and pre-commit hooks

Guard runs locally on a developer's machine as they edit code, different from continuous integration (CI) systems like Travis CI or GitHub Actions, which run tests after code is pushed. Guard is also different from pre-commit hooks, which run automatically before Git commits. Guard's strength is providing instant feedback during development: change a file, see the results immediately. CI is the wrong tool for that; it runs after the code leaves your machine. Pre-commit hooks block commits if tests fail, which is useful for preventing broken code from being pushed but slower than Guard because commits must wait. Guard is often used alongside both: developers use Guard for fast feedback during coding, pre-commit hooks to catch problems before pushing, and CI to verify across all platforms and configurations. This layering means Guard is for development velocity, not for replacing the safety checks that CI and pre-commit hooks provide.

Editorial conclusion

Guard is valuable for Ruby and Rails developers who tire of manually restarting tests or linters after code changes. It belongs in projects where you run tests frequently during development and want feedback fast. Teams should adopt Guard if they have a Guardfile that documents their development workflow and already use test runners or linters that respond to file changes. Before starting, verify that you have Bundler configured correctly and understand the difference between running `bundle exec guard` directly and using `bundle binstub guard` to avoid dependency problems. The core limitation is that Guard depends on the Watch gem for file system events, which may miss rapid bursts of file changes on some systems.

Frequently asked questions

Official sources

1. guard/guard on GitHub
2. Issues
3. License: MIT
4. README
5. Releases