Guard watches the files in your project directory, and responds to changes by running a configurable command or plugin.

This is very useful functionality. I feel that the Guard website makes it harder than necessary to get started though. Therefore I wrote this tutorial.

Why use Guard?

Example uses for Guard are:

• Automatically run your tests after your code changes
• Run bundle install when you edit your Gemfile
• Migrate your database when you change a migration
• Restart your Sinatra server after you edited your Ruby code

Basic Setup

Here are the basic steps to get started with Guard.

Install Gem

In the terminal, install the Guard gem:

$ gem install guard

Install a Plugin

Then install the guard-shell gem:

$ gem install guard-shell

This gem is a plugin for Guard. The reason why we add this plugin is that Guard is constructed such that it needs at least one plugin.

guard-shell in particular is a plugin that allows Guard to run Ruby or shell commands in response to file changes.

Make a Guardfile

Now we can generate a Guardfile. The Guardfile defines which files Guard will watch, and what it will do when one or more of these files change.

Run this command from your terminal:

$ guard init

This lets Guard generate a sample Guardfile and put it into your current directory.

The command output will look something like this:

12:02:56 - INFO - Writing new Guardfile to /Users/stefan/Projects/GuardTutorial/Guardfile
12:02:56 - INFO - shell guard added to Guardfile, feel free to edit it

Let's see what Guard generated as Guardfile:

(...many comments deleted...)
guard :shell do
  watch(/(.*).txt/) {|m| `tail #{m[0]}` }
end

The first line means "Run Guard with the shell plugin." Then the next line says "watch all files whose names match the path *.txt, and on changes run the shell command tail on the first modified file".

You can add more than one guard command to your Guard file, and you can also have multiple watch commands.

Replace the guard command with this code:

guard :shell do
  watch(//) do |modified_files|
    puts "Modified files: #{modified_files}"
    `tail #{modified_files[0]}`
  end
end

This new command should make the Guardfile more intuitive for you. It lets Guard watch all files, not just *.txt files. On file changes, it prints the changed files and runs tail on the first modified file.

Create a Source Code File

We need another file just so Guard has something to watch. Create a new source code file, like so:

$ echo "Hello World" > mysource.rb

Run Guard

Now it's time to run Guard:

$ guard

Then change the file mysource.rb and save it. You should see in your terminal:

Modified files: ["mysource.rb"]

Guard printed out the file name of the modified file and than ran tail on it, as defined in the Guardfile!

How to Move On

Now that you got over the initial hurdle of getting Guard set up, you can add plugins for your specific use case. The Guard plugin list to find the ones supporting your situation.

Run bundle install Each Time on Gemfile Save

See my follow up tutorial on how to use Guard to run bundle install automatically on changes to your Gemfile.

More Examples

For more examples, checkout the Rspec plugin or the Minitest plugin, and the Bundler plugin.