Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Guard is a command line tool to easily handle events on file system modifications.
Ruby
Pull request Compare This branch is 3 commits ahead, 2187 commits behind guard:master.

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
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

And add it to you Gemfile

gem 'growl'

On Linux

Install rb-inotify for inotify support

gem install rb-inotify

Install libnotify for libonity notification support

gem install libnotify

And add it to you Gemfile

gem '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

  • 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

    def initialize(watchers = [], options = {})
      super
      # init stuff here, thx!
    end

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

    # If one of those methods raise an exception, the Guard instance
    # will be removed from the active guard.

    # Call once when guard starts
    # Please override initialize method to init stuff
    def start
      true
    end

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

    # Call with Ctrl-Z signal
    # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
    def reload
      true
    end

    # Call with Ctrl-/ signal
    # This method should be principally used for long action like running all specs/tests/...
    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! Shame on me :)

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.