Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 417 lines (292 sloc) 10.567 kb
a6d0dab @rymai Use the SSL version of the Travis build image
rymai authored
1 Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png)](http://travis-ci.org/guard/guard)
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
2 =====
3
4 Guard is a command line tool that easily handle events on files modifications.
5
8f7034b @netzpirat Make sure questions go to the Google group/IRC and issues to GitHub.
netzpirat authored
6 If you have any questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
d2af050 Added Google group & irc links in Readme
Thibaud Guillaume-Gentil authored
7
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
8 Features
9 --------
10
11 * [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).
12 * [Inotify](http://en.wikipedia.org/wiki/Inotify) support on Linux ([rb-inotify gem, >= 0.5.1](https://rubygems.org/gems/rb-inotify) required).
057549a @rymai Readme cleanup
rymai authored
13 * [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support on Windows ([rb-fchange, >= 0.0.2](https://rubygems.org/gems/rb-fchange) required).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
14 * Polling on the other operating systems (help us to support more OS).
15 * Automatic & Super fast (when polling is not used) files modifications detection (even new files are detected).
16 * Growl notifications ([growlnotify](http://growl.info/documentation/growlnotify.php) & [growl gem](https://rubygems.org/gems/growl) required).
17 * Libnotify notifications ([libnotify gem](https://rubygems.org/gems/libnotify) required).
d7394e4 Bye bye 1.8.6 support.
Thibaud Guillaume-Gentil authored
18 * Tested on Ruby 1.8.7, 1.9.2 && ree.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
19
20 Install
21 -------
22
23 Install the gem:
24
b7137bb @rymai Made the README even more gorgeous!
rymai authored
25 ``` bash
6d5cb96 @rymai Removed unexpected "`" in README
rymai authored
26 $ gem install guard
b7137bb @rymai Made the README even more gorgeous!
rymai authored
27 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
28
d755765 @rymai Improved README
rymai authored
29 Add it to your Gemfile (inside the `development` group):
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
30
31 ``` ruby
32 gem 'guard'
33 ```
34
35 Generate an empty Guardfile with:
36
b7137bb @rymai Made the README even more gorgeous!
rymai authored
37 ``` bash
6d5cb96 @rymai Removed unexpected "`" in README
rymai authored
38 $ guard init
b7137bb @rymai Made the README even more gorgeous!
rymai authored
39 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
40
524af46 @tpope Make home Guardfile hidden
tpope authored
41 You may optionally place a .Guardfile in your home directory to use it across multiple projects.
b69aa76 Update README regarding Guardfile location
Aaron Kalin and Veezus Kreist authored
42
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
43 Add the guards you need to your Guardfile (see the existing guards below).
44
45 ### On Mac OS X
46
47 Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
48
b7137bb @rymai Made the README even more gorgeous!
rymai authored
49 ``` bash
6d5cb96 @rymai Removed unexpected "`" in README
rymai authored
50 $ gem install rb-fsevent
b7137bb @rymai Made the README even more gorgeous!
rymai authored
51 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
52
53 Install the Growl gem if you want notification support:
54
b7137bb @rymai Made the README even more gorgeous!
rymai authored
55 ``` bash
6d5cb96 @rymai Removed unexpected "`" in README
rymai authored
56 $ gem install growl
b7137bb @rymai Made the README even more gorgeous!
rymai authored
57 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
58
a3c8bbd Updated installation doc
Thibaud Guillaume-Gentil authored
59 And add them to your Gemfile:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
60
61 ``` ruby
a3c8bbd Updated installation doc
Thibaud Guillaume-Gentil authored
62 gem 'rb-fsevent'
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
63 gem 'growl'
64 ```
65
66 ### On Linux
67
68 Install the rb-inotify gem for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
69
b7137bb @rymai Made the README even more gorgeous!
rymai authored
70 ``` bash
6d5cb96 @rymai Removed unexpected "`" in README
rymai authored
71 $ gem install rb-inotify
b7137bb @rymai Made the README even more gorgeous!
rymai authored
72 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
73
74 Install the Libnotify gem if you want notification support:
75
b7137bb @rymai Made the README even more gorgeous!
rymai authored
76 ``` bash
6d5cb96 @rymai Removed unexpected "`" in README
rymai authored
77 $ gem install libnotify
b7137bb @rymai Made the README even more gorgeous!
rymai authored
78 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
79
a3c8bbd Updated installation doc
Thibaud Guillaume-Gentil authored
80 And add them to your Gemfile:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
81
82 ``` ruby
a3c8bbd Updated installation doc
Thibaud Guillaume-Gentil authored
83 gem 'rb-inotify'
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
84 gem 'libnotify'
85 ```
86
29069cd @stereobooster Update documentation for windows support
stereobooster authored
87 ### On Windows
88
89 Install the rb-fchange gem for [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support:
90
b7137bb @rymai Made the README even more gorgeous!
rymai authored
91 ``` bash
6d5cb96 @rymai Removed unexpected "`" in README
rymai authored
92 $ gem install rb-fchange
b7137bb @rymai Made the README even more gorgeous!
rymai authored
93 ```
29069cd @stereobooster Update documentation for windows support
stereobooster authored
94
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
95 Install the Notifu gem if you want notification support:
96
97 ``` bash
98 $ gem install rb-notifu
99 ```
100
a3c8bbd Updated installation doc
Thibaud Guillaume-Gentil authored
101 And add them to your Gemfile:
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
102
103 ``` ruby
a3c8bbd Updated installation doc
Thibaud Guillaume-Gentil authored
104 gem 'rb-fchange'
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
105 gem 'rb-notifu'
106 ```
107
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
108 Usage
109 -----
110
111 Just launch Guard inside your Ruby / Rails project with:
112
b7137bb @rymai Made the README even more gorgeous!
rymai authored
113 ``` bash
6d5cb96 @rymai Removed unexpected "`" in README
rymai authored
114 $ guard [start]
b7137bb @rymai Made the README even more gorgeous!
rymai authored
115 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
116
117 or if you use Bundler, to run the Guard executable specific to your bundle:
118
b7137bb @rymai Made the README even more gorgeous!
rymai authored
119 ``` bash
d755765 @rymai Improved README
rymai authored
120 $ bundle exec guard [start]
b7137bb @rymai Made the README even more gorgeous!
rymai authored
121 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
122
524af46 @tpope Make home Guardfile hidden
tpope authored
123 Guard will look for a Guardfile in your current directory. If it does not find one, it will look in your `$HOME` directory for a .Guardfile.
b69aa76 Update README regarding Guardfile location
Aaron Kalin and Veezus Kreist authored
124
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
125 Command line options
126 --------------------
127
d755765 @rymai Improved README
rymai authored
128 ### `--clear` option
129
130 Shell can be cleared after each change:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
131
b7137bb @rymai Made the README even more gorgeous!
rymai authored
132 ``` bash
133 $ guard --clear
134 $ guard -c # shortcut
135 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
136
d755765 @rymai Improved README
rymai authored
137 ### `--notify` option
138
139 Notifications (growl/libnotify) can be disabled:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
140
b7137bb @rymai Made the README even more gorgeous!
rymai authored
141 ``` bash
142 $ guard --notify false
f424854 Refactorized notifier enabling/disabling
Thibaud Guillaume-Gentil authored
143 $ guard -n f # shortcut
b7137bb @rymai Made the README even more gorgeous!
rymai authored
144 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
145
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
146 Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`
2f94f9e Fixed notification option
Thibaud Guillaume-Gentil authored
147
d755765 @rymai Improved README
rymai authored
148 ### `--group` option
149
150 Only certain guards groups can be run (see the Guardfile DSL below for creating groups):
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
151
b7137bb @rymai Made the README even more gorgeous!
rymai authored
152 ``` bash
153 $ guard --group group_name another_group_name
154 $ guard -g group_name another_group_name # shortcut
155 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
156
d755765 @rymai Improved README
rymai authored
157 ### `--debug` option
158
159 Guard can be run in debug mode:
bbe42f9 @rymai Added informations on the --debug option!
rymai authored
160
161 ``` bash
162 $ guard --debug
163 $ guard -d # shortcut
164 ```
165
166 An exhaustive list of options is available with:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
167
b7137bb @rymai Made the README even more gorgeous!
rymai authored
168 ``` bash
6d5cb96 @rymai Removed unexpected "`" in README
rymai authored
169 $ guard help [TASK]
b7137bb @rymai Made the README even more gorgeous!
rymai authored
170 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
171
172 Signal handlers
173 ---------------
174
175 Signal handlers are used to interact with Guard:
176
c8002ac @rymai Making the README more awesome
rymai authored
177 * `Ctrl-C` - Calls each guard's `#stop` method, in the same order they are declared in the Guardfile, and then quits Guard itself.
178 * `Ctrl-\` - Calls each guard's `#run_all` method, in the same order they are declared in the Guardfile.
179 * `Ctrl-Z` - Calls each guard's `#reload` method, in the same order they are declared in the Guardfile.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
180
c8002ac @rymai Making the README more awesome
rymai authored
181 You can read more about [configure the signal keyboard shortcuts](https://github.com/guard/guard/wiki/Configure-keyboard-shortcuts) in the wiki.
217069b @netzpirat Add wiki link on how to configure signal keyboard shortcuts.
netzpirat authored
182
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
183 Available Guards
184 ----------------
185
c8002ac @rymai Making the README more awesome
rymai authored
186 A list of the available guards is present [in the wiki](https://github.com/guard/guard/wiki/List-of-available-Guards).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
187
188 ### Add a guard to your Guardfile
189
d755765 @rymai Improved README
rymai authored
190 Add it to your Gemfile (inside the `development` group):
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
191
192 ``` ruby
193 gem '<guard-name>'
194 ```
195
0054af6 @docwhat Mention 'guard list' in README
docwhat authored
196 You can list all guards installed on your system with:
197
198 ``` bash
199 $ guard list
200 ```
201
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
202 Insert default guard's definition to your Guardfile by running this command:
203
b7137bb @rymai Made the README even more gorgeous!
rymai authored
204 ``` bash
205 $ guard init <guard-name>
206 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
207
d755765 @rymai Improved README
rymai authored
208 You are good to go, or you can modify your guards' definition to suit your needs.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
209
210 Guardfile DSL
211 -------------
212
d755765 @rymai Improved README
rymai authored
213 The Guardfile DSL consists of just three simple methods: `#guard`, `#watch` & `#group`.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
214
215 Required:
057549a @rymai Readme cleanup
rymai authored
216
d755765 @rymai Improved README
rymai authored
217 * The `#guard` method allows you to add a guard with an optional hash of options.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
218
219 Optional:
057549a @rymai Readme cleanup
rymai authored
220
c8002ac @rymai Making the README more awesome
rymai authored
221 * The `#watch` method allows you to define which files are supervised by this guard. An optional block can be added to overwrite the paths sent to the guard's `#run_on_change` method or to launch any arbitrary command.
d755765 @rymai Improved README
rymai authored
222 * The `#group` method allows you to group several guards together. Groups to be 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 on a certain part.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
223
224 Example:
225
226 ``` ruby
227 group 'backend' do
228 guard 'bundler' do
229 watch('Gemfile')
230 end
231
232 guard 'rspec', :cli => '--color --format doc' do
233 # Regexp watch patterns are matched with Regexp#match
d755765 @rymai Improved README
rymai authored
234 watch(%r{^spec/.+_spec\.rb$})
235 watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
236 watch(%r{^spec/models/.+\.rb$}) { ["spec/models", "spec/acceptance"] }
237 watch(%r{^spec/.+\.rb$}) { `say hello` }
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
238
239 # String watch patterns are matched with simple '=='
240 watch('spec/spec_helper.rb') { "spec" }
241 end
242 end
243
244 group 'frontend' do
245 guard 'coffeescript', :output => 'public/javascripts/compiled' do
d755765 @rymai Improved README
rymai authored
246 watch(%r{^app/coffeescripts/.+\.coffee$})
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
247 end
248
249 guard 'livereload' do
d755765 @rymai Improved README
rymai authored
250 watch(%r{^app/.+\.(erb|haml)$})
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
251 end
252 end
253 ```
254
c8002ac @rymai Making the README more awesome
rymai authored
255 ### Using a Guardfile without the `guard` binary
256
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
257 The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
258 Available options are as follow:
259
260 * `:guardfile` - The path to a valid Guardfile.
261 * `:guardfile_contents` - A string representing the content of a valid Guardfile
262
d755765 @rymai Improved README
rymai authored
263 Remember, without any options given, Guard will look for a Guardfile in your current directory and if it does not find one, it will look for it in your `$HOME` directory.
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
264
265 For instance, you could use it as follow:
266
267 ``` ruby
268 gem 'guard'
269 require 'guard'
270
271 Guard.setup
272
d755765 @rymai Improved README
rymai authored
273 Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
274 # or
275 Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
276 guard 'rspec' do
d755765 @rymai Improved README
rymai authored
277 watch(%r{^spec/.+_spec\.rb$})
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
278 end
279 ")
280 ```
281
7ba4819 @johnbintz documentation and man page updates
johnbintz authored
282 ### Listing defined guards/groups for the current project
283
284 You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
285
286 ``` bash
287 # guard -T
288
289 (global):
290 shell
291 Group backend:
292 bundler
0c9cf69 @NickClark Fix unmatched quotes in readme
NickClark authored
293 rspec: cli => "--color --format doc"
7ba4819 @johnbintz documentation and man page updates
johnbintz authored
294 Group frontend:
295 coffeescript: output => "public/javascripts/compiled"
296 livereload
297 ```
298
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
299 Create a new guard
300 ------------------
301
057549a @rymai Readme cleanup
rymai authored
302 Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
303
c8002ac @rymai Making the README more awesome
rymai authored
304 ```
305 .travis.yml # bonus point!
306 CHANGELOG.md # bonus point!
307 Gemfile
308 guard-name.gemspec
309 Guardfile
310 lib/
311 guard/
312 guard-name/
313 templates/
314 Guardfile # needed for `guard init <guard-name>`
315 version.rb
316 guard-name.rb
317 test/ # or spec/
318 README.md
319 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
320
d755765 @rymai Improved README
rymai authored
321 `Guard::GuardName` (in `lib/guard/guard-name.rb`) must inherit from `Guard::Guard` and should overwrite at least one of the five basic `Guard::Guard` instance methods.
322
323 Here is an example scaffold for `lib/guard/guard-name.rb`:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
324
325 ``` ruby
326 require 'guard'
327 require 'guard/guard'
328
329 module Guard
330 class GuardName < Guard
331
332 def initialize(watchers=[], options={})
333 super
334 # init stuff here, thx!
335 end
336
337 # =================
338 # = Guard methods =
339 # =================
340
341 # If one of those methods raise an exception, the Guard::GuardName instance
342 # will be removed from the active guards.
343
344 # Called once when Guard starts
345 # Please override initialize method to init stuff
346 def start
347 true
348 end
349
350 # Called on Ctrl-C signal (when Guard quits)
351 def stop
352 true
353 end
354
355 # Called on Ctrl-Z signal
356 # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
357 def reload
358 true
359 end
360
af7dbb9 @tinogomes Edited README.markdown via GitHub
tinogomes authored
361 # Called on Ctrl-\ signal
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
362 # This method should be principally used for long action like running all specs/tests/...
363 def run_all
364 true
365 end
366
367 # Called on file(s) modifications
368 def run_on_change(paths)
369 true
370 end
371
372 end
373 end
374 ```
375
d755765 @rymai Improved README
rymai authored
376 Please take a look at the [existing guards' source code](https://github.com/guard/guard/wiki/List-of-available-Guards) for more concrete example and inspiration.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
377
378 Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
379
380 ``` ruby
381 require 'guard/guard'
382
383 module ::Guard
057549a @rymai Readme cleanup
rymai authored
384 class InlineGuard < ::Guard::Guard
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
385 def run_all
386 true
387 end
388
389 def run_on_change(paths)
390 true
391 end
392 end
393 end
394 ```
395
d755765 @rymai Improved README
rymai authored
396 Here is a very cool example by [@avdi](https://github.com/avdi) : http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis
397
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
398 Development
399 -----------
400
401 * Source hosted at [GitHub](https://github.com/guard/guard).
8f7034b @netzpirat Make sure questions go to the Google group/IRC and issues to GitHub.
netzpirat authored
402 * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
403
d755765 @rymai Improved README
rymai authored
404 Pull requests are very welcome! Make sure your patches are well tested. Please create a topic branch for every separate change you make. Please **do not change** the version in your pull-request.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
405
8f7034b @netzpirat Make sure questions go to the Google group/IRC and issues to GitHub.
netzpirat authored
406 For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
407
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
408 Author
409 ------
410
ead039b Fixed README
Thibaud Guillaume-Gentil authored
411 [Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
057549a @rymai Readme cleanup
rymai authored
412
413 Contributors
414 ------
415
b69aa76 Update README regarding Guardfile location
Aaron Kalin and Veezus Kreist authored
416 https://github.com/guard/guard/contributors
Something went wrong with that request. Please try again.