Skip to content
Newer
Older
100644 411 lines (288 sloc) 10.2 KB
284747b Updated travis-ci png
Thibaud Guillaume-Gentil authored
1 Guard [![Build Status](http://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 Readme cleanup
Rémy Coutable 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 Made the README even more gorgeous!
Rémy Coutable authored
25 ``` bash
6d5cb96 Removed unexpected "`" in README
Rémy Coutable authored
26 $ gem install guard
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
27 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
28
d755765 Improved README
Rémy Coutable 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 Made the README even more gorgeous!
Rémy Coutable authored
37 ``` bash
6d5cb96 Removed unexpected "`" in README
Rémy Coutable authored
38 $ guard init
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
39 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
40
b69aa76 Update README regarding Guardfile location
Aaron Kalin and Veezus Kreist authored
41 You may optionally place this Guardfile in your home directory to use it across multiple projects.
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 Made the README even more gorgeous!
Rémy Coutable authored
49 ``` bash
6d5cb96 Removed unexpected "`" in README
Rémy Coutable authored
50 $ gem install rb-fsevent
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
51 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
52
53 Install the Growl gem if you want notification support:
54
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
55 ``` bash
6d5cb96 Removed unexpected "`" in README
Rémy Coutable authored
56 $ gem install growl
b7137bb Made the README even more gorgeous!
Rémy Coutable 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 Made the README even more gorgeous!
Rémy Coutable authored
70 ``` bash
6d5cb96 Removed unexpected "`" in README
Rémy Coutable authored
71 $ gem install rb-inotify
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
72 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
73
74 Install the Libnotify gem if you want notification support:
75
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
76 ``` bash
6d5cb96 Removed unexpected "`" in README
Rémy Coutable authored
77 $ gem install libnotify
b7137bb Made the README even more gorgeous!
Rémy Coutable 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 Made the README even more gorgeous!
Rémy Coutable authored
91 ``` bash
6d5cb96 Removed unexpected "`" in README
Rémy Coutable authored
92 $ gem install rb-fchange
b7137bb Made the README even more gorgeous!
Rémy Coutable 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 Made the README even more gorgeous!
Rémy Coutable authored
113 ``` bash
6d5cb96 Removed unexpected "`" in README
Rémy Coutable authored
114 $ guard [start]
b7137bb Made the README even more gorgeous!
Rémy Coutable 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 Made the README even more gorgeous!
Rémy Coutable authored
119 ``` bash
d755765 Improved README
Rémy Coutable authored
120 $ bundle exec guard [start]
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
121 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
122
11c3e0b Keeping the Changelog up to date and improved the Readme
Rémy Coutable 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 one.
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 Improved README
Rémy Coutable authored
128 ### `--clear` option
129
130 Shell can be cleared after each change:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
131
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
132 ``` bash
133 $ guard --clear
134 $ guard -c # shortcut
135 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
136
d755765 Improved README
Rémy Coutable authored
137 ### `--notify` option
138
139 Notifications (growl/libnotify) can be disabled:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
140
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
141 ``` bash
142 $ guard --notify false
f424854 Refactorized notifier enabling/disabling
Thibaud Guillaume-Gentil authored
143 $ guard -n f # shortcut
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
144 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
145
11c3e0b Keeping the Changelog up to date and improved the Readme
Rémy Coutable 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 Improved README
Rémy Coutable 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 Made the README even more gorgeous!
Rémy Coutable 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 Improved README
Rémy Coutable authored
157 ### `--debug` option
158
159 Guard can be run in debug mode:
bbe42f9 Added informations on the --debug option!
Rémy Coutable 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 Made the README even more gorgeous!
Rémy Coutable authored
168 ``` bash
6d5cb96 Removed unexpected "`" in README
Rémy Coutable authored
169 $ guard help [TASK]
b7137bb Made the README even more gorgeous!
Rémy Coutable 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 Making the README more awesome
Rémy Coutable 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 Making the README more awesome
Rémy Coutable 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 Making the README more awesome
Rémy Coutable 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 Improved README
Rémy Coutable 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
196 Insert default guard's definition to your Guardfile by running this command:
197
b7137bb Made the README even more gorgeous!
Rémy Coutable authored
198 ``` bash
199 $ guard init <guard-name>
200 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
201
d755765 Improved README
Rémy Coutable authored
202 You are good to go, or you can modify your guards' definition to suit your needs.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
203
204 Guardfile DSL
205 -------------
206
d755765 Improved README
Rémy Coutable authored
207 The Guardfile DSL consists of just three simple methods: `#guard`, `#watch` & `#group`.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
208
209 Required:
057549a Readme cleanup
Rémy Coutable authored
210
d755765 Improved README
Rémy Coutable authored
211 * The `#guard` method allows you to add a guard with an optional hash of options.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
212
213 Optional:
057549a Readme cleanup
Rémy Coutable authored
214
c8002ac Making the README more awesome
Rémy Coutable authored
215 * 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 Improved README
Rémy Coutable authored
216 * 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
217
218 Example:
219
220 ``` ruby
221 group 'backend' do
222 guard 'bundler' do
223 watch('Gemfile')
224 end
225
226 guard 'rspec', :cli => '--color --format doc' do
227 # Regexp watch patterns are matched with Regexp#match
d755765 Improved README
Rémy Coutable authored
228 watch(%r{^spec/.+_spec\.rb$})
229 watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
230 watch(%r{^spec/models/.+\.rb$}) { ["spec/models", "spec/acceptance"] }
231 watch(%r{^spec/.+\.rb$}) { `say hello` }
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
232
233 # String watch patterns are matched with simple '=='
234 watch('spec/spec_helper.rb') { "spec" }
235 end
236 end
237
238 group 'frontend' do
239 guard 'coffeescript', :output => 'public/javascripts/compiled' do
d755765 Improved README
Rémy Coutable authored
240 watch(%r{^app/coffeescripts/.+\.coffee$})
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
241 end
242
243 guard 'livereload' do
d755765 Improved README
Rémy Coutable authored
244 watch(%r{^app/.+\.(erb|haml)$})
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
245 end
246 end
247 ```
248
c8002ac Making the README more awesome
Rémy Coutable authored
249 ### Using a Guardfile without the `guard` binary
250
11c3e0b Keeping the Changelog up to date and improved the Readme
Rémy Coutable authored
251 The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
252 Available options are as follow:
253
254 * `:guardfile` - The path to a valid Guardfile.
255 * `:guardfile_contents` - A string representing the content of a valid Guardfile
256
d755765 Improved README
Rémy Coutable authored
257 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 Keeping the Changelog up to date and improved the Readme
Rémy Coutable authored
258
259 For instance, you could use it as follow:
260
261 ``` ruby
262 gem 'guard'
263 require 'guard'
264
265 Guard.setup
266
d755765 Improved README
Rémy Coutable authored
267 Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
11c3e0b Keeping the Changelog up to date and improved the Readme
Rémy Coutable authored
268 # or
269 Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
270 guard 'rspec' do
d755765 Improved README
Rémy Coutable authored
271 watch(%r{^spec/.+_spec\.rb$})
11c3e0b Keeping the Changelog up to date and improved the Readme
Rémy Coutable authored
272 end
273 ")
274 ```
275
7ba4819 @johnbintz documentation and man page updates
johnbintz authored
276 ### Listing defined guards/groups for the current project
277
278 You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
279
280 ``` bash
281 # guard -T
282
283 (global):
284 shell
285 Group backend:
286 bundler
287 rspec: cli => "--color --format doc'
288 Group frontend:
289 coffeescript: output => "public/javascripts/compiled"
290 livereload
291 ```
292
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
293 Create a new guard
294 ------------------
295
057549a Readme cleanup
Rémy Coutable authored
296 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
297
c8002ac Making the README more awesome
Rémy Coutable authored
298 ```
299 .travis.yml # bonus point!
300 CHANGELOG.md # bonus point!
301 Gemfile
302 guard-name.gemspec
303 Guardfile
304 lib/
305 guard/
306 guard-name/
307 templates/
308 Guardfile # needed for `guard init <guard-name>`
309 version.rb
310 guard-name.rb
311 test/ # or spec/
312 README.md
313 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
314
d755765 Improved README
Rémy Coutable authored
315 `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.
316
317 Here is an example scaffold for `lib/guard/guard-name.rb`:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
318
319 ``` ruby
320 require 'guard'
321 require 'guard/guard'
322
323 module Guard
324 class GuardName < Guard
325
326 def initialize(watchers=[], options={})
327 super
328 # init stuff here, thx!
329 end
330
331 # =================
332 # = Guard methods =
333 # =================
334
335 # If one of those methods raise an exception, the Guard::GuardName instance
336 # will be removed from the active guards.
337
338 # Called once when Guard starts
339 # Please override initialize method to init stuff
340 def start
341 true
342 end
343
344 # Called on Ctrl-C signal (when Guard quits)
345 def stop
346 true
347 end
348
349 # Called on Ctrl-Z signal
350 # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
351 def reload
352 true
353 end
354
af7dbb9 @tinogomes Edited README.markdown via GitHub
tinogomes authored
355 # Called on Ctrl-\ signal
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
356 # This method should be principally used for long action like running all specs/tests/...
357 def run_all
358 true
359 end
360
361 # Called on file(s) modifications
362 def run_on_change(paths)
363 true
364 end
365
366 end
367 end
368 ```
369
d755765 Improved README
Rémy Coutable authored
370 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
371
372 Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
373
374 ``` ruby
375 require 'guard/guard'
376
377 module ::Guard
057549a Readme cleanup
Rémy Coutable authored
378 class InlineGuard < ::Guard::Guard
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
379 def run_all
380 true
381 end
382
383 def run_on_change(paths)
384 true
385 end
386 end
387 end
388 ```
389
d755765 Improved README
Rémy Coutable authored
390 Here is a very cool example by [@avdi](https://github.com/avdi) : http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis
391
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
392 Development
393 -----------
394
395 * 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
396 * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
397
d755765 Improved README
Rémy Coutable authored
398 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
399
8f7034b @netzpirat Make sure questions go to the Google group/IRC and issues to GitHub.
netzpirat authored
400 For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
401
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
402 Author
403 ------
404
ead039b Fixed README
Thibaud Guillaume-Gentil authored
405 [Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
057549a Readme cleanup
Rémy Coutable authored
406
407 Contributors
408 ------
409
b69aa76 Update README regarding Guardfile location
Aaron Kalin and Veezus Kreist authored
410 https://github.com/guard/guard/contributors
Something went wrong with that request. Please try again.