Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Guard is a command line tool to easily handle events on files modifications (FSEvent / Inotify / Polling support).

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
images
lib
spec
.gitignore
CHANGELOG.rdoc
Gemfile
Gemfile.lock
Guardfile
LICENSE
README.rdoc
Rakefile
guard.gemspec

README.rdoc

Guard

Guard is a command line tool to easly handle events on files modifications.

Features

Install

Install the gem:

gem install guard

Add it to your Gemfile (inside test group):

gem 'guard'

Generate an empty Guardfile with:

guard init

Add guard(s) you need (see available guards below)

On Mac OS X

Install rb-fsevent for FSEvent support

gem install rb-fsevent

Install growl for Growl notification support

gem install growl

On Linux

Install rb-inotify for inotify support

gem install rb-inotify

Install libnotify for libonity notification support

gem install libnotify

Usage

Just launch Guard inside your ruby/rails project with:

guard

Shell can be cleared after each change with:

guard -c

Options list is available with:

guard help [TASK]

Signal handlers are used to interact with Guard:

  • Ctrl-C - Quit Guard (call stop guard(s) method before)

  • Ctrl-\ - Call run_all guard(s) method

  • Ctrl-Z - Call reload guard(s) method

Available Guards

guard ideas:

  • guard-spork

  • guard-cucumber

  • guard-bundler

  • others ideas?

Add a guard to your Guardfile

Add it to your Gemfile (inside test group):

gem '<guard-name>'

Add guard definition to your Guardfile by running this command:

guard init <guard-name>

You are good to go!

Create a guard

Create a new guard is very easy, just create a new gem with this basic structure:

lib/
  guard/
    guard-name/
      templates/
        Guardfile (needed for guard init <guard-name>)
    guard-name.rb

lib/guard/guard-name.rb inherit from guard/guard and should overwrite at least one of the five guard methods. Example:

require 'guard'
require 'guard/guard'

module Guard
  class GuardName < Guard

    # ================
    # = Guard method =
    # ================

    # Call once when guard starts
    def start
      true
    end

    # Call with Ctrl-C signal (when Guard quit)
    def stop
      true
    end

    # Call with Ctrl-Z signal
    def reload
      true
    end

    # Call with Ctrl-/ signal
    def run_all
      true
    end

    # Call on file(s) modifications
    def run_on_change(paths)
      true
    end

  end
end

Looks at available guards code for more concrete example.

Guardfile DSL

Guardfile DSL consists of just two simple methods: guard & watch. Example:

guard 'rspec', :version => 2 do
  watch('^spec/(.*)_spec.rb')
  watch('^lib/(.*)\.rb')        { |m| "spec/lib/#{m[1]}_spec.rb" }
  watch('^spec/spec_helper.rb') { "spec" }
  watch('^spec/spec_helper.rb') { `say hello` }
end
  • “guard” method allow to add a guard with an optional options hash

  • “watch” method allow to define which files are supervised per this guard. A optional block can be added to overwrite path sending to run_on_change guard method or launch simple command.

TODO

  • Add more specs, help are welcome because I'm not sure about how to test stuff like this :-)

Development

Pull requests are very welcome! Make sure your patches are well tested. Please create a topic branch for every separate change you make.

Authors

Thibaud Guillaume-Gentil

Something went wrong with that request. Please try again.