guard 0.8.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/LICENSE CHANGED
@@ -1,20 +1,20 @@
1
- Copyright (c) 2011 Thibaud Guillaume-Gentil
2
-
3
- Permission is hereby granted, free of charge, to any person obtaining
4
- a copy of this software and associated documentation files (the
5
- "Software"), to deal in the Software without restriction, including
6
- without limitation the rights to use, copy, modify, merge, publish,
7
- distribute, sublicense, and/or sell copies of the Software, and to
8
- permit persons to whom the Software is furnished to do so, subject to
9
- the following conditions:
10
-
11
- The above copyright notice and this permission notice shall be
12
- included in all copies or substantial portions of the Software.
13
-
14
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
1
+ Copyright (c) 2011 Thibaud Guillaume-Gentil
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
20
  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.md CHANGED
@@ -1,434 +1,434 @@
1
- Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png)](http://travis-ci.org/guard/guard)
2
- =====
3
-
4
- Guard is a command line tool that easily handle events on files modifications.
5
-
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).
7
-
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).
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).
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
- * Visual notifications on Mac OSX ([Growl](http://growl.info)), Linux ([Libnotify](http://developer.gnome.org/libnotify)) and Windows ([Notifu](http://www.paralint.com/projects/notifu)).
17
- * Tested against Ruby 1.8.7, 1.9.2, REE and the latest versions of JRuby & Rubinius.
18
-
19
- Screencast
20
- ----------
21
-
22
- Ryan Bates made a Railscast on Guard, you can view it here: http://railscasts.com/episodes/264-guard
23
-
24
- Install
25
- -------
26
-
27
- Install the gem:
28
-
29
- $ gem install guard
30
-
31
- Or add it to your Gemfile (inside the `development` group):
32
-
33
- gem 'guard'
34
-
35
- and install it via Bundler:
36
-
37
- $ bundle install
38
-
39
- Generate an empty Guardfile with:
40
-
41
- $ guard init
42
-
43
- You may optionally place a .Guardfile in your home directory to use it across multiple projects.
44
- Also note that if a `.guard.rb` is found in your home directory, it will be appended to the Guardfile.
45
-
46
- Add the guards you need to your Guardfile (see the existing guards below).
47
-
48
- ### On Mac OS X
49
-
50
- Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
51
-
52
- $ gem install rb-fsevent
53
-
54
- You have two possibilities:
55
-
56
- Use the [growl_notify gem](https://rubygems.org/gems/growl_notify) (recommended):
57
-
58
- $ gem install growl_notify
59
-
60
- Use the [growlnotify](http://growl.info/extras.php#growlnotify) (cli tool for growl) + the [growl gem](https://rubygems.org/gems/growl).
61
-
62
- $ brew install growlnotify
63
- $ gem install growl
64
-
65
- And add them to your Gemfile:
66
-
67
- gem 'rb-fsevent'
68
- gem 'growl_notify' # or gem 'growl'
69
-
70
- The difference between growl and growl_notify is that growl_notify uses AppleScript to
71
- display a message, whereas growl uses the `growlnotify` command. In general the AppleScript
72
- approach is preferred, but you may also use the older growl gem. Have a look at the
73
- [Guard Wiki](https://github.com/guard/guard/wiki/Use-growl_notify-or-growl-gem) for more information.
74
-
75
- ### On Linux
76
-
77
- Install the [rb-inotify gem](https://rubygems.org/gems/rb-inotify) for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
78
-
79
- $ gem install rb-inotify
80
-
81
- Install the [libnotify gem](https://rubygems.org/gems/libnotify) if you want visual notification support:
82
-
83
- $ gem install libnotify
84
-
85
- And add them to your Gemfile:
86
-
87
- gem 'rb-inotify'
88
- gem 'libnotify'
89
-
90
- ### On Windows
91
-
92
- Install the [rb-fchange gem](https://rubygems.org/gems/rb-fchange) for [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support:
93
-
94
- $ gem install rb-fchange
95
-
96
- Install the [win32console gem](https://rubygems.org/gems/win32console) if you want colors in your terminal:
97
-
98
- $ gem install win32console
99
-
100
- Install the [rb-notifu gem](https://rubygems.org/gems/rb-notifu) if you want visual notification support:
101
-
102
- $ gem install rb-notifu
103
-
104
- And add them to your Gemfile:
105
-
106
- gem 'rb-fchange'
107
- gem 'rb-notifu'
108
- gem 'win32console'
109
-
110
- Usage
111
- -----
112
-
113
- Just launch Guard inside your Ruby / Rails project with:
114
-
115
- $ guard [start]
116
-
117
- or if you use Bundler, to run the Guard executable specific to your bundle:
118
-
119
- $ bundle exec guard [start]
120
-
121
- 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.
122
-
123
- Command line options
124
- --------------------
125
-
126
- ### `-c`/`--clear` option
127
-
128
- Shell can be cleared after each change:
129
-
130
- $ guard --clear
131
- $ guard -c # shortcut
132
-
133
- ### `-n`/`--notify` option
134
-
135
- Notifications (growl/libnotify) can be disabled:
136
-
137
- $ guard --notify false
138
- $ guard -n f # shortcut
139
-
140
- Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`
141
-
142
- ### `-g`/`--group` option
143
-
144
- Only certain guards groups can be run (see the Guardfile DSL below for creating groups):
145
-
146
- $ guard --group group_name another_group_name
147
- $ guard -g group_name another_group_name # shortcut
148
-
149
- ### `-d`/`--debug` option
150
-
151
- Guard can be run in debug mode:
152
-
153
- $ guard --debug
154
- $ guard -d # shortcut
155
-
156
- ### `-w`/`--watchdir` option
157
-
158
- Guard can watch in any directory (instead of the current directory):
159
-
160
- $ guard --watchdir ~/your/fancy/project
161
- $ guard -w ~/your/fancy/project # shortcut
162
-
163
- ### `-G`/`--guardfile` option
164
-
165
- Guard can use a Guardfile not located in the current directory:
166
-
167
- $ guard --guardfile ~/.your_global_guardfile
168
- $ guard -G ~/.your_global_guardfile # shortcut
169
-
170
- ### `-A`/`--watch-all-modifications` option
171
-
172
- Guard can optionally watch all file modifications like moves or deletions with:
173
-
174
- ``` bash
175
- $ guard start -A
176
- $ guard start --watch-all-modifications
177
- ```
178
-
179
- An exhaustive list of options is available with:
180
-
181
- $ guard help [TASK]
182
-
183
- Interactions
184
- ------------
185
-
186
- **From version >= 0.7.0 Posix Signal handlers are no more used to interact with Guard. If you're using a version < 0.7, please refer to the [README in the v0.6 branch](https://github.com/guard/guard/blob/v0.6/README.md).**
187
-
188
- When Guard do nothing you can interact with by entering a command + hitting enter:
189
-
190
- * `stop|quit|exit|s|q|e + enter` - Calls each guard's `#stop` method, in the same order they are declared in the Guardfile, and then quits Guard itself.
191
- * `reload|r|z + enter` - Calls each guard's `#reload` method, in the same order they are declared in the Guardfile.
192
- * `pause|p + enter` - Toggle files modification listening. Useful when switching git branches.
193
- * `just enter (no commands)` - Calls each guard's `#run_all` method, in the same order they are declared in the Guardfile.
194
-
195
- Available Guards
196
- ----------------
197
-
198
- A list of the available guards is present [in the wiki](https://github.com/guard/guard/wiki/List-of-available-Guards).
199
-
200
- ### Add a guard to your Guardfile
201
-
202
- Add it to your Gemfile (inside the `development` group):
203
-
204
- gem '<guard-name>'
205
-
206
- You can list all guards installed on your system with:
207
-
208
- $ guard list
209
-
210
- Insert default guard's definition to your Guardfile by running this command:
211
-
212
- $ guard init <guard-name>
213
-
214
- You are good to go, or you can modify your guards' definition to suit your needs.
215
-
216
- Guardfile DSL
217
- -------------
218
-
219
- The Guardfile DSL consists of the following methods:
220
-
221
- * `#guard`: allows you to add a guard with an optional hash of options.
222
- * `#watch`: 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.
223
- * `#group`: 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. Guards that don't belong to a group are considered global and are always run.
224
- * `#callback`: allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`, `run_all` and `run_on_change` guards' method. You can even insert more hooks inside these methods. Please [checkout the Wiki page](https://github.com/guard/guard/wiki/Hooks-and-callbacks) for more details.
225
- * `#ignore_paths`: allows you to ignore top level directories altogether. This comes is handy when you have large amounts of non-source data in you project. By default .bundle, .git, log, tmp, and vendor are ignored. Currently it is only possible to ignore the immediate descendants of the watched directory.
226
-
227
- Example:
228
-
229
- ignore_paths 'foo', 'bar'
230
-
231
- group 'backend' do
232
- guard 'bundler' do
233
- watch('Gemfile')
234
- end
235
-
236
- guard 'rspec', :cli => '--color --format doc' do
237
- # Regexp watch patterns are matched with Regexp#match
238
- watch(%r{^spec/.+_spec\.rb$})
239
- watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
240
- watch(%r{^spec/models/.+\.rb$}) { ["spec/models", "spec/acceptance"] }
241
- watch(%r{^spec/.+\.rb$}) { `say hello` }
242
-
243
- # String watch patterns are matched with simple '=='
244
- watch('spec/spec_helper.rb') { "spec" }
245
- end
246
- end
247
-
248
- group 'frontend' do
249
- guard 'coffeescript', :output => 'public/javascripts/compiled' do
250
- watch(%r{^app/coffeescripts/.+\.coffee$})
251
- end
252
-
253
- guard 'livereload' do
254
- watch(%r{^app/.+\.(erb|haml)$})
255
- end
256
- end
257
-
258
- Using a Guardfile without the `guard` binary
259
- --------------------------------------------
260
-
261
- The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
262
- Available options are as follow:
263
-
264
- * `:guardfile` - The path to a valid Guardfile.
265
- * `:guardfile_contents` - A string representing the content of a valid Guardfile
266
-
267
- 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.
268
-
269
- For instance, you could use it as follow:
270
-
271
- gem 'guard'
272
- require 'guard'
273
-
274
- Guard.setup
275
-
276
- Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
277
- # or
278
- Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
279
- guard 'rspec' do
280
- watch(%r{^spec/.+_spec\.rb$})
281
- end
282
- ")
283
-
284
- ### Listing defined guards/groups for the current project
285
-
286
- You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
287
-
288
- $ guard -T
289
-
290
- (global):
291
- shell
292
- Group backend:
293
- bundler
294
- rspec: cli => "--color --format doc"
295
- Group frontend:
296
- coffeescript: output => "public/javascripts/compiled"
297
- livereload
298
-
299
- User config file
300
- ----------------
301
-
302
- If a `.guard.rb` is found in your home directory, it will be appended to
303
- the Guardfile. This can be used for tasks you want guard to handle but
304
- other users probably don't. For example, indexing your source tree with
305
- [Ctags](http://ctags.sourceforge.net):
306
-
307
- guard 'shell' do
308
- watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
309
- end
310
-
311
- Create a new guard
312
- ------------------
313
-
314
- Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
315
-
316
- .travis.yml # bonus point!
317
- CHANGELOG.md # bonus point!
318
- Gemfile
319
- guard-name.gemspec
320
- Guardfile
321
- lib/
322
- guard/
323
- guard-name/
324
- templates/
325
- Guardfile # needed for `guard init <guard-name>`
326
- version.rb
327
- guard-name.rb
328
- test/ # or spec/
329
- README.md
330
-
331
- `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.
332
-
333
- Here is an example scaffold for `lib/guard/guard-name.rb`:
334
-
335
- require 'guard'
336
- require 'guard/guard'
337
-
338
- module Guard
339
- class GuardName < Guard
340
-
341
- def initialize(watchers = [], options = {})
342
- super
343
- # init stuff here, thx!
344
- end
345
-
346
- # =================
347
- # = Guard methods =
348
- # =================
349
-
350
- # If one of those methods raise an exception, the Guard::GuardName instance
351
- # will be removed from the active guards.
352
-
353
- # Called once when Guard starts
354
- # Please override initialize method to init stuff
355
- def start
356
- true
357
- end
358
-
359
- # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits)
360
- def stop
361
- true
362
- end
363
-
364
- # Called when `reload|r|z + enter` is pressed
365
- # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
366
- def reload
367
- true
368
- end
369
-
370
- # Called when just `enter` is pressed
371
- # This method should be principally used for long action like running all specs/tests/...
372
- def run_all
373
- true
374
- end
375
-
376
- # Called on file(s) modifications
377
- def run_on_change(paths)
378
- true
379
- end
380
-
381
- # Called on file(s) deletions
382
- def run_on_deletion(paths)
383
- true
384
- end
385
-
386
- end
387
- end
388
-
389
- 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.
390
-
391
- Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
392
-
393
- require 'guard/guard'
394
-
395
- module ::Guard
396
- class InlineGuard < ::Guard::Guard
397
- def run_all
398
- true
399
- end
400
-
401
- def run_on_change(paths)
402
- true
403
- end
404
- end
405
- end
406
-
407
- Here is a very cool example by [@avdi](https://github.com/avdi) : http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis
408
-
409
- Development
410
- -----------
411
-
412
- * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
413
- * Source hosted at [GitHub](https://github.com/guard/guard).
414
- * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
415
-
416
- Pull requests are very welcome! Please try to follow these simple "rules", though:
417
-
418
- - Please create a topic branch for every separate change you make;
419
- - Make sure your patches are well tested;
420
- - Update the README (if applicable);
421
- - Update the CHANGELOG (maybe not for a typo but don't hesitate!);
422
- - Please **do not change** the version number.
423
-
424
- For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
425
-
426
- Author
427
- ------
428
-
429
- [Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
430
-
431
- Contributors
432
- ------------
433
-
434
- https://github.com/guard/guard/contributors
1
+ Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png)](http://travis-ci.org/guard/guard)
2
+ =====
3
+
4
+ Guard is a command line tool that easily handle events on files modifications.
5
+
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).
7
+
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).
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).
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
+ * Visual notifications on Mac OSX ([Growl](http://growl.info)), Linux ([Libnotify](http://developer.gnome.org/libnotify)) and Windows ([Notifu](http://www.paralint.com/projects/notifu)).
17
+ * Tested against Ruby 1.8.7, 1.9.2, REE and the latest versions of JRuby & Rubinius.
18
+
19
+ Screencast
20
+ ----------
21
+
22
+ Ryan Bates made a Railscast on Guard, you can view it here: http://railscasts.com/episodes/264-guard
23
+
24
+ Install
25
+ -------
26
+
27
+ Install the gem:
28
+
29
+ $ gem install guard
30
+
31
+ Or add it to your Gemfile (inside the `development` group):
32
+
33
+ gem 'guard'
34
+
35
+ and install it via Bundler:
36
+
37
+ $ bundle install
38
+
39
+ Generate an empty Guardfile with:
40
+
41
+ $ guard init
42
+
43
+ You may optionally place a .Guardfile in your home directory to use it across multiple projects.
44
+ Also note that if a `.guard.rb` is found in your home directory, it will be appended to the Guardfile.
45
+
46
+ Add the guards you need to your Guardfile (see the existing guards below).
47
+
48
+ ### On Mac OS X
49
+
50
+ Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
51
+
52
+ $ gem install rb-fsevent
53
+
54
+ You have two possibilities:
55
+
56
+ Use the [growl_notify gem](https://rubygems.org/gems/growl_notify) (recommended):
57
+
58
+ $ gem install growl_notify
59
+
60
+ Use the [growlnotify](http://growl.info/extras.php#growlnotify) (cli tool for growl) + the [growl gem](https://rubygems.org/gems/growl).
61
+
62
+ $ brew install growlnotify
63
+ $ gem install growl
64
+
65
+ And add them to your Gemfile:
66
+
67
+ gem 'rb-fsevent'
68
+ gem 'growl_notify' # or gem 'growl'
69
+
70
+ The difference between growl and growl_notify is that growl_notify uses AppleScript to
71
+ display a message, whereas growl uses the `growlnotify` command. In general the AppleScript
72
+ approach is preferred, but you may also use the older growl gem. Have a look at the
73
+ [Guard Wiki](https://github.com/guard/guard/wiki/Use-growl_notify-or-growl-gem) for more information.
74
+
75
+ ### On Linux
76
+
77
+ Install the [rb-inotify gem](https://rubygems.org/gems/rb-inotify) for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
78
+
79
+ $ gem install rb-inotify
80
+
81
+ Install the [libnotify gem](https://rubygems.org/gems/libnotify) if you want visual notification support:
82
+
83
+ $ gem install libnotify
84
+
85
+ And add them to your Gemfile:
86
+
87
+ gem 'rb-inotify'
88
+ gem 'libnotify'
89
+
90
+ ### On Windows
91
+
92
+ Install the [rb-fchange gem](https://rubygems.org/gems/rb-fchange) for [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support:
93
+
94
+ $ gem install rb-fchange
95
+
96
+ Install the [win32console gem](https://rubygems.org/gems/win32console) if you want colors in your terminal:
97
+
98
+ $ gem install win32console
99
+
100
+ Install the [rb-notifu gem](https://rubygems.org/gems/rb-notifu) if you want visual notification support:
101
+
102
+ $ gem install rb-notifu
103
+
104
+ And add them to your Gemfile:
105
+
106
+ gem 'rb-fchange'
107
+ gem 'rb-notifu'
108
+ gem 'win32console'
109
+
110
+ Usage
111
+ -----
112
+
113
+ Just launch Guard inside your Ruby / Rails project with:
114
+
115
+ $ guard [start]
116
+
117
+ or if you use Bundler, to run the Guard executable specific to your bundle:
118
+
119
+ $ bundle exec guard [start]
120
+
121
+ 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.
122
+
123
+ Command line options
124
+ --------------------
125
+
126
+ ### `-c`/`--clear` option
127
+
128
+ Shell can be cleared after each change:
129
+
130
+ $ guard --clear
131
+ $ guard -c # shortcut
132
+
133
+ ### `-n`/`--notify` option
134
+
135
+ Notifications (growl/libnotify) can be disabled:
136
+
137
+ $ guard --notify false
138
+ $ guard -n f # shortcut
139
+
140
+ Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`
141
+
142
+ ### `-g`/`--group` option
143
+
144
+ Only certain guards groups can be run (see the Guardfile DSL below for creating groups):
145
+
146
+ $ guard --group group_name another_group_name
147
+ $ guard -g group_name another_group_name # shortcut
148
+
149
+ ### `-d`/`--debug` option
150
+
151
+ Guard can be run in debug mode:
152
+
153
+ $ guard --debug
154
+ $ guard -d # shortcut
155
+
156
+ ### `-w`/`--watchdir` option
157
+
158
+ Guard can watch in any directory (instead of the current directory):
159
+
160
+ $ guard --watchdir ~/your/fancy/project
161
+ $ guard -w ~/your/fancy/project # shortcut
162
+
163
+ ### `-G`/`--guardfile` option
164
+
165
+ Guard can use a Guardfile not located in the current directory:
166
+
167
+ $ guard --guardfile ~/.your_global_guardfile
168
+ $ guard -G ~/.your_global_guardfile # shortcut
169
+
170
+ ### `-A`/`--watch-all-modifications` option
171
+
172
+ Guard can optionally watch all file modifications like moves or deletions with:
173
+
174
+ ``` bash
175
+ $ guard start -A
176
+ $ guard start --watch-all-modifications
177
+ ```
178
+
179
+ An exhaustive list of options is available with:
180
+
181
+ $ guard help [TASK]
182
+
183
+ Interactions
184
+ ------------
185
+
186
+ **From version >= 0.7.0 Posix Signal handlers are no more used to interact with Guard. If you're using a version < 0.7, please refer to the [README in the v0.6 branch](https://github.com/guard/guard/blob/v0.6/README.md).**
187
+
188
+ When Guard do nothing you can interact with by entering a command + hitting enter:
189
+
190
+ * `stop|quit|exit|s|q|e + enter` - Calls each guard's `#stop` method, in the same order they are declared in the Guardfile, and then quits Guard itself.
191
+ * `reload|r|z + enter` - Calls each guard's `#reload` method, in the same order they are declared in the Guardfile.
192
+ * `pause|p + enter` - Toggle files modification listening. Useful when switching git branches.
193
+ * `just enter (no commands)` - Calls each guard's `#run_all` method, in the same order they are declared in the Guardfile.
194
+
195
+ Available Guards
196
+ ----------------
197
+
198
+ A list of the available guards is present [in the wiki](https://github.com/guard/guard/wiki/List-of-available-Guards).
199
+
200
+ ### Add a guard to your Guardfile
201
+
202
+ Add it to your Gemfile (inside the `development` group):
203
+
204
+ gem '<guard-name>'
205
+
206
+ You can list all guards installed on your system with:
207
+
208
+ $ guard list
209
+
210
+ Insert default guard's definition to your Guardfile by running this command:
211
+
212
+ $ guard init <guard-name>
213
+
214
+ You are good to go, or you can modify your guards' definition to suit your needs.
215
+
216
+ Guardfile DSL
217
+ -------------
218
+
219
+ The Guardfile DSL consists of the following methods:
220
+
221
+ * `#guard`: allows you to add a guard with an optional hash of options.
222
+ * `#watch`: 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.
223
+ * `#group`: 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. Guards that don't belong to a group are considered global and are always run.
224
+ * `#callback`: allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`, `run_all` and `run_on_change` guards' method. You can even insert more hooks inside these methods. Please [checkout the Wiki page](https://github.com/guard/guard/wiki/Hooks-and-callbacks) for more details.
225
+ * `#ignore_paths`: allows you to ignore top level directories altogether. This comes is handy when you have large amounts of non-source data in you project. By default .bundle, .git, log, tmp, and vendor are ignored. Currently it is only possible to ignore the immediate descendants of the watched directory.
226
+
227
+ Example:
228
+
229
+ ignore_paths 'foo', 'bar'
230
+
231
+ group 'backend' do
232
+ guard 'bundler' do
233
+ watch('Gemfile')
234
+ end
235
+
236
+ guard 'rspec', :cli => '--color --format doc' do
237
+ # Regexp watch patterns are matched with Regexp#match
238
+ watch(%r{^spec/.+_spec\.rb$})
239
+ watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
240
+ watch(%r{^spec/models/.+\.rb$}) { ["spec/models", "spec/acceptance"] }
241
+ watch(%r{^spec/.+\.rb$}) { `say hello` }
242
+
243
+ # String watch patterns are matched with simple '=='
244
+ watch('spec/spec_helper.rb') { "spec" }
245
+ end
246
+ end
247
+
248
+ group 'frontend' do
249
+ guard 'coffeescript', :output => 'public/javascripts/compiled' do
250
+ watch(%r{^app/coffeescripts/.+\.coffee$})
251
+ end
252
+
253
+ guard 'livereload' do
254
+ watch(%r{^app/.+\.(erb|haml)$})
255
+ end
256
+ end
257
+
258
+ Using a Guardfile without the `guard` binary
259
+ --------------------------------------------
260
+
261
+ The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
262
+ Available options are as follow:
263
+
264
+ * `:guardfile` - The path to a valid Guardfile.
265
+ * `:guardfile_contents` - A string representing the content of a valid Guardfile
266
+
267
+ 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.
268
+
269
+ For instance, you could use it as follow:
270
+
271
+ gem 'guard'
272
+ require 'guard'
273
+
274
+ Guard.setup
275
+
276
+ Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
277
+ # or
278
+ Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
279
+ guard 'rspec' do
280
+ watch(%r{^spec/.+_spec\.rb$})
281
+ end
282
+ ")
283
+
284
+ ### Listing defined guards/groups for the current project
285
+
286
+ You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
287
+
288
+ $ guard -T
289
+
290
+ (global):
291
+ shell
292
+ Group backend:
293
+ bundler
294
+ rspec: cli => "--color --format doc"
295
+ Group frontend:
296
+ coffeescript: output => "public/javascripts/compiled"
297
+ livereload
298
+
299
+ User config file
300
+ ----------------
301
+
302
+ If a `.guard.rb` is found in your home directory, it will be appended to
303
+ the Guardfile. This can be used for tasks you want guard to handle but
304
+ other users probably don't. For example, indexing your source tree with
305
+ [Ctags](http://ctags.sourceforge.net):
306
+
307
+ guard 'shell' do
308
+ watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
309
+ end
310
+
311
+ Create a new guard
312
+ ------------------
313
+
314
+ Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
315
+
316
+ .travis.yml # bonus point!
317
+ CHANGELOG.md # bonus point!
318
+ Gemfile
319
+ guard-name.gemspec
320
+ Guardfile
321
+ lib/
322
+ guard/
323
+ guard-name/
324
+ templates/
325
+ Guardfile # needed for `guard init <guard-name>`
326
+ version.rb
327
+ guard-name.rb
328
+ test/ # or spec/
329
+ README.md
330
+
331
+ `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.
332
+
333
+ Here is an example scaffold for `lib/guard/guard-name.rb`:
334
+
335
+ require 'guard'
336
+ require 'guard/guard'
337
+
338
+ module Guard
339
+ class GuardName < Guard
340
+
341
+ def initialize(watchers = [], options = {})
342
+ super
343
+ # init stuff here, thx!
344
+ end
345
+
346
+ # =================
347
+ # = Guard methods =
348
+ # =================
349
+
350
+ # If one of those methods raise an exception, the Guard::GuardName instance
351
+ # will be removed from the active guards.
352
+
353
+ # Called once when Guard starts
354
+ # Please override initialize method to init stuff
355
+ def start
356
+ true
357
+ end
358
+
359
+ # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits)
360
+ def stop
361
+ true
362
+ end
363
+
364
+ # Called when `reload|r|z + enter` is pressed
365
+ # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
366
+ def reload
367
+ true
368
+ end
369
+
370
+ # Called when just `enter` is pressed
371
+ # This method should be principally used for long action like running all specs/tests/...
372
+ def run_all
373
+ true
374
+ end
375
+
376
+ # Called on file(s) modifications
377
+ def run_on_change(paths)
378
+ true
379
+ end
380
+
381
+ # Called on file(s) deletions
382
+ def run_on_deletion(paths)
383
+ true
384
+ end
385
+
386
+ end
387
+ end
388
+
389
+ 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.
390
+
391
+ Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
392
+
393
+ require 'guard/guard'
394
+
395
+ module ::Guard
396
+ class InlineGuard < ::Guard::Guard
397
+ def run_all
398
+ true
399
+ end
400
+
401
+ def run_on_change(paths)
402
+ true
403
+ end
404
+ end
405
+ end
406
+
407
+ Here is a very cool example by [@avdi](https://github.com/avdi) : http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis
408
+
409
+ Development
410
+ -----------
411
+
412
+ * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
413
+ * Source hosted at [GitHub](https://github.com/guard/guard).
414
+ * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
415
+
416
+ Pull requests are very welcome! Please try to follow these simple "rules", though:
417
+
418
+ - Please create a topic branch for every separate change you make;
419
+ - Make sure your patches are well tested;
420
+ - Update the README (if applicable);
421
+ - Update the CHANGELOG (maybe not for a typo but don't hesitate!);
422
+ - Please **do not change** the version number.
423
+
424
+ For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
425
+
426
+ Author
427
+ ------
428
+
429
+ [Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
430
+
431
+ Contributors
432
+ ------------
433
+
434
+ https://github.com/guard/guard/contributors