Hire a Guard for Your Project

Of all of the new tools that I've picked up using for development in the past six months, there is one that has come to stand above the others for its nearly universal utility. That tool is Guard.

Guard is a RubyGem but don't let that fool you into thinking it's only useful for Ruby projects. Guard is essentially an autotest for everything. It provides a general purpose set of tools for watching when files are changed in your project and taking action based on it. You can use it to do just about anything, but common uses will include:

• Re-running automated tests after a file changes.
• Automatically compiling scripts or assets for a project (e.g. minification).
• Installing new dependencies that may be added to the project.

With a little creativity and a slight bit of Ruby coding, though, you can make your entire project's workflow run smoother and faster. It's like having a telepathic robot buddy who just goes around doing whatever you were about to do next without having to be told (except the first time).

Getting Started With Guard

Guard requires a basic Ruby setup. Once you have Ruby and RubyGems installed, simply run:

gem install guard 

This will get you started. If you want to make it easier for others to run your guards as well, you should also install Bundler to encapsulate the different guard gems you'll be using:

gem install bundler 

Once you have these installed, in the root of your project run:

guard init 

This will initialize a Guardfile in the project root that will be telling Guard what to do going forward. From here, you will want to install some of the Guard extension gems that let you quickly create automation for your project. Some of my favorites:

• guard-rspec: Automatically run RSpec tests based on easy-to-customize patterns. I use this on almost every Ruby project these days.
• guard-coffeescript: Compile Coffeescript into Javascript lickety-split. Even though Coffeescript has its own automatic build command with the -w option, I prefer Guard because it lets you define the configuration once and, in addition, run a single process for all of your project's automation.
• guard-process: This is the guard for anything they haven't made a guard for yet. Using this you can quickly and easily run shell commands as soon as files change, giving you the ability to do almost anything.
• guard-sass: Never write vanilla CSS again. Using Guard SASS you can automatically compile SASS giving you the full power of mixins, variables, and more for all your styles.

There's a full list of guards that include all kinds of magic (there's even guard-livereload that can automatically refresh your browser whenever you make a change to a project), and it's dead simple to create new Guard libraries if what you want isn't available (or you can just use guard-process).

Standing Guard

For any of the Guard gems you install, you can add them to your Guardfile by running:

guard init guardname 

Where guardname might be rspec or coffeescript, etc. That will fill your Guardfile with a basic implementation of the given guard and is usually enough for you to tweak the settings to your liking without further documentation.

There's a great example of using Guard for a big Rails project, but I'm not just using it for Ruby. I've used Guard on jQuery plugins, Node.js projects, even static websites that I've been building (more on that a little later).

To make it easier for others to jump into your project with Guard, it also helps to use Bundler to maintain a Gemfile that points to the various guards you're using for the specific project. Just run bundle init to get Bundler up and running then edit the file to look something like this:

source 'http://rubygems.org'  gem 'guard' gem 'guard-coffeescript' gem 'guard-process' 

Then run bundle install. Once your gems are installed and you've set up your Guardfile, just run:

bundle exec guard 

Guard will start up right away and your project now has some smooth automation action. Guard will even reload itself if you modify the Guardfile, so feel free to tweak as you go!

Guard in the Real World

I'm going to post just a couple examples of Guardfiles I've been using in my projects recently to give you an idea of its versatility.

Guarding a jQuery Plugin

Here's the Guardfile for Sketch.js, a jQuery plugin that I just released:

# Automatically build the source Coffeescript into the lib directory guard 'coffeescript', :input => 'src', :output => 'lib', :bare => true # Also automatically build the test Coffeescripts guard 'coffeescript', :input => 'test', :output => 'test', :bare => true  # Run Docco  guard 'process', :name => 'Docco', :command => 'docco src/sketch.coffee' do   watch %r{src/.+.coffee} end  # Copy the newly created lib file for minification. guard 'process', :name => 'Copy to min', :command => 'cp lib/sketch.js lib/sketch.min.js' do   watch %r{lib/sketch.js} end  # Use uglify.js to minify the Javascript for maximum smallness guard 'uglify', :destination_file => "lib/sketch.min.js" do   watch (%r{lib/sketch.min.js}) end 

This enabled my workflow to be instantaneous: I could immediately look at my work whether it was in my examples, my tests, or my documentation. Everything was immediately built and I never had to slow myself down with run and refresh cycles.

Guarding a Node.js Project

I've probably only scratched the surface here, but a simple Node.js project that I'm currently working on has this for a Guardfile:

guard 'coffeescript', :input => 'src', :output => '.', :bare => true  guard 'process', :name => 'NPM', :command => 'npm install' do   watch %r{package.json} end 

Notice that using guard-process I'm automatically installing new dependencies that may arise when the package.json file is altered.

Guarding a Static Website

I've come to really appreciate both Coffeescript and SASS as worthwhile abstractions, so even if I'm building something that's vanilla HTML I might have a Guardfile like this:

guard 'sass', :input => 'sass', :output => 'css' guard 'coffeescript', :input => 'coffeescripts', :output => 'javascripts' 

These are all basic examples, but that (to me) is the point: Guard is so simple to use and basic that you can drop it in every project you build. I've yet to run into something that I don't want to use Guard on.

Tip of the Iceberg

I've been expanding my usage of Guard into, well, everything that I'm working on. Thus far it's included Ruby, Javascript, and static HTML projects, but if I move on to other things Guard will be coming with me. For instance, I'd love to build a Guard to automatically recompile and run an Android application whenever the XML views change. The possibilities are limitless.

If you're not using Guard, give it a try on one of your current projects. I think you'll quickly find immense satisfaction in being able to simply cd into the project directory, run guard, and know that you are completely ready to roll. I'd like to see a Guardfile in every open source project I fork, every client project I clone…Guard is so useful that I simply want to be using it all the time. And that is the mark of a great tool.