Guard is a command line tool to easily handle events on files modifications (FSEvent / Inotify / Polling support).
9ff627cfaa
so that we don't get duplicate entries for same file. This solves problem with commonly used Linux editors (e.g. Vim, Emacs) that generate multiple inotify events on file save. http://schettino72.wordpress.com/2010/03/07/inotify-text-editors-emacs-vim/ |
||
---|---|---|
bin | ||
images | ||
lib | ||
spec | ||
.gitignore | ||
CHANGELOG.rdoc | ||
Gemfile | ||
guard.gemspec | ||
Guardfile | ||
LICENSE | ||
Rakefile | ||
README.rdoc |
= Guard Guard is a command line tool that easily handle events on files modifications. == Features - {FSEvent}[http://en.wikipedia.org/wiki/FSEvents] support on Mac OS X 10.5+ (without RubyCocoa!, {rb-fsevent gem, >= 0.3.5}[https://rubygems.org/gems/rb-fsevent] required) - {Inotify}[http://en.wikipedia.org/wiki/Inotify] support on Linux ({rb-inotify gem, >= 0.5.1}[https://rubygems.org/gems/rb-inotify] required) - Polling for others (help us to support more systems) - Super fast change detection (when polling not used) - Automatic files modifications detection (even new files are detected) - Growl notification ({growlnotify}[http://growl.info/documentation/growlnotify.php] & {growl gem}[https://rubygems.org/gems/growl] required) - Libnotify notification ({libnotify gem}[https://rubygems.org/gems/libnotify] required) - Tested on Ruby 1.8.6, 1.8.7 & 1.9.2 == 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 the guards you need (see available guards below) === On Mac OS X Install rb-fsevent for {FSEvent}[http://en.wikipedia.org/wiki/FSEvents] 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}[http://en.wikipedia.org/wiki/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 or if you use Bundler, to run the Guard executable specific to your bundle: bundle exec guard == Command line options Shell can be cleared after each change with: guard --clear guard -c # shortcut The guards to start can be specified by group (see Guardfile DSL below) specifying the `--group` (or `-g`) option: guard --group group_name another_group_name guard -g group_name another_group_name # shortcut Options list is available with: guard help [TASK] == Signal handlers Signal handlers are used to interact with Guard: - Ctrl-C - Quit Guard (call each guard's run_all method, in the same order they are declared in the Guarfile) - Ctrl-\ - Call each guard's run_all method, in the same order they are declared in the Guarfile - Ctrl-Z - Call each guard's reload method, in the same order they are declared in the Guarfile == Available Guards - {guard-bundler}[https://github.com/guard/guard-bundler] by {Yann Lugrin}[https://github.com/yannlugrin] - {guard-coffeescript}[https://github.com/guard/guard-coffeescript] by {Michael Kessler}[https://github.com/netzpirat] - {guard-compass}[https://github.com/guard/guard-compass] by {Olivier Amblet}[https://github.com/oliamb] - {guard-cucumber}[https://github.com/guard/guard-cucumber] by {Michael Kessler}[https://github.com/netzpirat] - {guard-ego}[https://github.com/guard/guard-ego] by {Fabio Kuhn}[https://github.com/mordaroso] - {guard-jammit}[https://github.com/guard/guard-jammit] by {Pelle Braendgaard}[https://github.com/pelle] - {guard-less}[https://github.com/guard/guard-less] by {Brendan Erwin}[https://github.com/brendanjerwin] - {guard-livereload}[https://github.com/guard/guard-livereload] by {Thibaud Guillaume-Gentil}[https://github.com/thibaudgg] - {guard-minitest}[https://github.com/guard/guard-minitest] by {Yann Lugrin}[https://github.com/yannlugrin] - {guard-nanoc}[https://github.com/guard/guard-nanoc] by {Yann Lugrin}[https://github.com/yannlugrin] - {guard-passenger}[https://github.com/guard/guard-passenger] by {Fabio Kuhn}[https://github.com/mordaroso] - {guard-rspec}[https://github.com/guard/guard-rspec] by {Thibaud Guillaume-Gentil}[https://github.com/thibaudgg] - {guard-sass}[https://github.com/guard/guard-sass] by {Joshua Hawxwell}[https://github.com/hawx] - {guard-shell}[https://github.com/guard/guard-shell] by {Joshua Hawxwell}[https://github.com/hawx] - {guard-soca}[https://github.com/guard/guard-soca] by {Luke Amdor}[https://github.com/rubbish] - {guard-spork}[https://github.com/guard/guard-spork] by {Thibaud Guillaume-Gentil}[https://github.com/thibaudgg] - {guard-stendhal}[https://github.com/guard/guard-stendhal] by {Josep Mª Bach}[https://github.com/txus] - {guard-test}[https://github.com/guard/guard-test] by {Rémy Coutable}[https://github.com/rymai] === 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! == Guardfile DSL The Guardfile DSL consists of just three simple main methods: `guard`, `watch` & `group`. Required: - The `guard` method allows you to add a guard with an optional options hash. - The `watch` method allows you to define which files are supervised per this guard. A optional block can be added to overwrite path sent to run_on_change guard method or launch simple command. Optional: - The `group` method allows you to group several guards. Groups to run can be specified with the Guard DSL option `--group` (or `-g`). This comes in handy especially when you have a huge Guardfile and want to focus your development. Example: group 'backend' do guard 'bundler' do watch('Gemfile') end guard 'rspec' do # Regexp watch patterns are matched with Regexp#match watch(%r{^spec/(.+)_spec\.rb}) watch(%r{^lib/(.+)\.rb}) { |m| "spec/lib/#{m[1]}_spec.rb" } watch(%r{^spec/models/.+\.rb}) { ["spec/models", "spec/acceptance"] } watch(%r{^spec/.+\.rb}) { `say hello` } # String watch patterns are matched with simple '==' watch('spec/spec_helper.rb') { "spec" } end end group 'frontend' do guard 'coffeescript', :output => 'public/javascripts/compiled' do watch(%r{app/coffeescripts/.+\.coffee}) end guard 'livereload' do watch(%r{app/.+\.(erb|haml)}) end end == 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. == Development - Source hosted at {GitHub}[https://github.com/guard/guard] - Report issues/Questions/Feature requests on {GitHub Issues}[https://github.com/guard/guard/issues] 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}[https://github.com/thibaudgg]