guard/guard: Ruby File Watching That Runs Your Tasks

What Guard actually solves, and for whom

Guard reacts to file system modifications by running rules you write. The README frames the motivation as avoiding "mundane, repetitive actions and commands such as relaunching tools after changing source files or configurations." That is the whole pitch, and it is deliberately narrow.

The tool is for people already inside a Ruby workflow. The README names software developers, web designers, writers and other specialists, and lists use cases including an IDE replacement, web development tooling, responsive build systems, project task automation and monitoring system services. Those are broad claims, but the implementation is not: Guard is a dispatcher. It watches, matches and invokes. The task itself comes from a plugin.

That split matters when you evaluate it. If you want a test runner that starts on save, Guard alone will not give you one. You install Guard plus a plugin, and the plugin supplies the behaviour. The README points to a wiki page listing known plugins and notes more than 300 exist on RubyGems under the guard- prefix. The count is a statement about ecosystem breadth, not about quality or maintenance of any individual plugin, and the README does not vouch for them.

The consequence is that your real dependency is the plugin, not Guard. A project with a well-maintained plugin gets a smooth experience. A project whose plugin has gone quiet inherits that problem regardless of how current the core gem is.

The mechanism: Listen, the Guardfile, and plugin dispatch

File system changes are handled by the Listen gem, which the README calls out directly under features. Guard does not implement platform-specific file watching itself; it delegates that to Listen and concentrates on matching changed paths against rules and invoking the right plugin.

The rules live in a Guardfile. Guard looks for Guardfile or guardfile.rb in the current directory when it starts, and if neither exists it falls back to .Guardfile in your $HOME directory. That fallback is worth knowing about: a machine with a home-directory Guardfile will silently apply it in a project that has none, which can produce behaviour that looks like it comes from nowhere.

The Guardfile is written in a Ruby DSL. The README links to Guardfile examples and to a page on the Guardfile DSL rather than inlining the syntax, so the authoritative description of the DSL is on the wiki, not in the README. Plugins ship templates that generate their own configuration blocks, which is why the init step exists.

Startup is a single command run from your project directory. Guard then sits in the foreground and reports on changes as they happen. Interaction happens on the console, and the README documents that Guard accepts signals, with the details on the wiki rather than in the repository README. If you plan to drive Guard from a script or a process manager, read that signals page first: the README does not enumerate the signals itself.

Installing guard and running it the first time

The README says the simplest way to install Guard is Bundler, and it is explicit that you should always run Guard through Bundler to avoid errors. Add the gem to the development group of your Gemfile:

group :development do
  gem 'guard'
end

Then install it:

$ bundle

Generate an empty Guardfile in the project root with the init command:

$ bundle exec guard init

After that, start Guard through Bundler:

$ bundle exec guard

The README does not describe what the generated Guardfile contains, only that it is empty. You are expected to fill it by adding plugins, each of which contributes its own template through the same init command. Adding a plugin means adding its gem to the same development group:

group :development do
  gem '<guard-plugin-name>'
end

If typing bundle exec repeatedly is the friction point, the README offers three routes. The recommended one is bundle binstub guard, which creates bin/guard in the project so that bin/guard behaves exactly like bundle exec guard. The second is a shell alias such as alias be="bundle exec" so you can type be guard, which the README notes works for every command run in the Bundler context. The third is the RUBYGEMS_GEMDEPS environment variable, set to - to autodetect the Gemfile in the current or parent directories, or set to the path of your Gemfile. The README flags that this RubyGems feature is still under development and lacks many Bundler features, so it is the weakest of the three options. For RubyGems older than 2.2.0, the README points to the Rubygems Bundler project instead.

One platform note in the README: on Mac OS X, if Guard does not react to file changes or Pry behaves strangely, the guidance is to add proper Readline support to Ruby on macOS, following a wiki page.

Where Guard is the wrong tool

The dependency on Bundler is the sharpest limitation, and the README states it plainly: always run Guard through Bundler. That means a project without a Gemfile is not a supported context for the documented workflow. You can install the gem globally, but you are then outside the path the README describes and outside the isolation it is trying to give you.

The second limitation is the plugin gap. Guard matches events and dispatches; it does not run tests, compile assets or restart services. If no plugin exists for your task, or the one that exists does not cover your case, Guard gives you a DSL and a watcher and nothing else. The README's own framing of the project as a tool for building smart and responsive workflows is really a description of what plugins let you build.

The third is configuration discovery. The README documents the fallback but does not describe a way to disable it, and it does not document rollback or recovery if a generated Guardfile or plugin template writes something you did not want. Treat the generated files as files to review, the same as any generator output.

The fourth is scope creep. Guard is a foreground process tied to your terminal session. The README describes console interaction and signals but does not present Guard as a service supervisor. If your requirement is a long-running daemon with restart policies, Guard is the wrong layer, and the README does not claim otherwise.

Guard compared with a plain watch command

The obvious alternative is a generic file-watching utility that runs a shell command when paths change. The difference is in where the logic lives. A watch command typically takes a path pattern and a command string, and everything else is your shell's problem: deciding which files matter, avoiding duplicate runs, and handling the output.

Guard moves that logic into a Ruby DSL and into plugins. The Guardfile expresses rules in the same language as the project, so a plugin can inspect the changed path and decide what to run rather than blindly executing a command. Plugins also carry their own defaults and templates, which is why guard init can produce a working configuration for a plugin without you writing the matching rules by hand.

The trade is portability. A watch command works in any repository in any language. Guard's documented path assumes Ruby, a Gemfile and Bundler, and its useful behaviour assumes a plugin exists for your task. If you maintain projects in several languages, a generic watcher keeps one mental model; Guard keeps one model per Ruby project and gives you plugin templates in exchange.

There is also a notification difference. The README lists support for visual system notifications as a feature, which a bare watch command does not provide. Whether that matters depends on whether you are watching the terminal or watching a desktop notification.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-07-16. The most recent release listed is v2.20.2, published the same day, following v2.20.1 on 2026-02-02 and v2.20.0 on 2026-01-16. That is a release cadence of roughly one minor or patch release every few months over the period shown, which is a factual description of the tags rather than a promise about the future.

Guard is licensed under MIT. In practical terms that is a permissive licence, and the repository ships a LICENSE file at the top level. This is not legal advice; if your organisation has licence review requirements, the LICENSE file is the thing to read.

Upgrade cost is dominated by the plugin ecosystem rather than the core gem. The README's release process describes bumping the version in lib/guard/version.rb and following semver, so the core gem signals breaking changes through major versions. Plugins version independently, and the README does not describe a compatibility matrix between Guard versions and plugin versions. That absence is the real upgrade risk: a Guard major bump can leave you checking each plugin's own release notes, and the README gives you no consolidated place to do that.

The README also notes the project is tested against Ruby 2.4.x, 2.5.x, 2.6.x, JRuby and Rubinius, with the exact versions in .travis.yml. If your environment runs a Ruby outside that set, the README does not state support for it, and .travis.yml is the file to check rather than assuming.

Editorial conclusion

Adopt Guard if you already work in a Bundler-managed Ruby or Rails project and want file-change reactions defined in a readable Guardfile, with plugins supplying the actual work. Do not adopt it if you need one self-contained tool with no Ruby dependency, or if your project has no Gemfile. Before committing, verify that a plugin exists for your task, check which Ruby versions your environment runs against the versions listed in .travis.yml, and confirm that your team will consistently invoke it as bundle exec guard rather than a bare guard.

Frequently asked questions

Official sources

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