Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 394 lines (275 sloc) 10.098 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 @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
196 Insert default guard's definition to your Guardfile by running this command:
197
b7137bb @rymai Made the README even more gorgeous!
rymai authored
198 ``` bash
199 $ guard init <guard-name>
200 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
201
d755765 @rymai Improved README
rymai 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 @rymai Improved README
rymai 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 @rymai Readme cleanup
rymai authored
210
d755765 @rymai Improved README
rymai 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 @rymai Readme cleanup
rymai authored
214
c8002ac @rymai Making the README more awesome
rymai 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 @rymai Improved README
rymai 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 @rymai Improved README
rymai 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 @rymai Improved README
rymai authored
240 watch(%r{^app/coffeescripts/.+\.coffee$})
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
241 end
242
243 guard 'livereload' do
d755765 @rymai Improved README
rymai authored
244 watch(%r{^app/.+\.(erb|haml)$})
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
245 end
246 end
247 ```
248
c8002ac @rymai Making the README more awesome
rymai authored
249 ### Using a Guardfile without the `guard` binary
250
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai 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 @rymai Improved README
rymai 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 @rymai Keeping the Changelog up to date and improved the Readme
rymai 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 @rymai Improved README
rymai authored
267 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
268 # or
269 Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
270 guard 'rspec' do
d755765 @rymai Improved README
rymai authored
271 watch(%r{^spec/.+_spec\.rb$})
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
272 end
273 ")
274 ```
275
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
276 Create a new guard
277 ------------------
278
057549a @rymai Readme cleanup
rymai authored
279 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
280
c8002ac @rymai Making the README more awesome
rymai authored
281 ```
282 .travis.yml # bonus point!
283 CHANGELOG.md # bonus point!
284 Gemfile
285 guard-name.gemspec
286 Guardfile
287 lib/
288 guard/
289 guard-name/
290 templates/
291 Guardfile # needed for `guard init <guard-name>`
292 version.rb
293 guard-name.rb
294 test/ # or spec/
295 README.md
296 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
297
d755765 @rymai Improved README
rymai authored
298 `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.
299
300 Here is an example scaffold for `lib/guard/guard-name.rb`:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
301
302 ``` ruby
303 require 'guard'
304 require 'guard/guard'
305
306 module Guard
307 class GuardName < Guard
308
309 def initialize(watchers=[], options={})
310 super
311 # init stuff here, thx!
312 end
313
314 # =================
315 # = Guard methods =
316 # =================
317
318 # If one of those methods raise an exception, the Guard::GuardName instance
319 # will be removed from the active guards.
320
321 # Called once when Guard starts
322 # Please override initialize method to init stuff
323 def start
324 true
325 end
326
327 # Called on Ctrl-C signal (when Guard quits)
328 def stop
329 true
330 end
331
332 # Called on Ctrl-Z signal
333 # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
334 def reload
335 true
336 end
337
af7dbb9 @tinogomes Edited README.markdown via GitHub
tinogomes authored
338 # Called on Ctrl-\ signal
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
339 # This method should be principally used for long action like running all specs/tests/...
340 def run_all
341 true
342 end
343
344 # Called on file(s) modifications
345 def run_on_change(paths)
346 true
347 end
348
349 end
350 end
351 ```
352
d755765 @rymai Improved README
rymai authored
353 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
354
355 Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
356
357 ``` ruby
358 require 'guard/guard'
359
360 module ::Guard
057549a @rymai Readme cleanup
rymai authored
361 class InlineGuard < ::Guard::Guard
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
362 def run_all
363 true
364 end
365
366 def run_on_change(paths)
367 true
368 end
369 end
370 end
371 ```
372
d755765 @rymai Improved README
rymai authored
373 Here is a very cool example by [@avdi](https://github.com/avdi) : http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis
374
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
375 Development
376 -----------
377
378 * 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
379 * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
380
d755765 @rymai Improved README
rymai authored
381 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
382
8f7034b @netzpirat Make sure questions go to the Google group/IRC and issues to GitHub.
netzpirat authored
383 For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
384
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
385 Author
386 ------
387
ead039b Fixed README
Thibaud Guillaume-Gentil authored
388 [Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
057549a @rymai Readme cleanup
rymai authored
389
390 Contributors
391 ------
392
b69aa76 Update README regarding Guardfile location
Aaron Kalin and Veezus Kreist authored
393 https://github.com/guard/guard/contributors
Something went wrong with that request. Please try again.