guard 0.7.0 → 0.8.0

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/CHANGELOG.md CHANGED
@@ -1,3 +1,22 @@
1
+ ## 0.8.0 - September 28, 2011
2
+
3
+ ### Bugs fixes:
4
+
5
+ - Pull request [#137](https://github.com/guard/guard/pull/137): Fix interacting with tools like ruby-debug. ([@hron][] & [@netzpirat][])
6
+ - Pull request [#138](https://github.com/guard/guard/pull/138): Fixed comments in example scaffold to reference interactions. ([@rmm5t][] & [@netzpirat][])
7
+
8
+ ### New feature:
9
+
10
+ - Pull request [#136](https://github.com/guard/guard/pull/136): New CLI `:watch_all_modifications`/`-A` option to watch for deleted and moved files too. ([@limeyd][] & [@netzpirat][])
11
+ - Issue [#97](https://github.com/guard/guard/issues/97): Guard dependencies. Task execution can now be halted if a Guard throws `:task_has_failed` and `Guard::Dsl#group` options include `:halt_on_fail => true`. ([@rymai][])
12
+ - Issue [#121](https://github.com/guard/guard/issues/121): `Guard.guards` and `Guard.groups` are now smart accessors. Filters can be passed to find a specific Guard/group or several Guards/groups that match (see YARDoc). ([@rymai][] & [@ches][])
13
+ - New `Guard::Group` class to store groups defined in Guardfile (with `Guard::Dsl#group`). ([@rymai][])
14
+
15
+ ### Improvement:
16
+
17
+ - Specs refactoring. ([@netzpirat][])
18
+ - Full YARD documentation. ([@netzpirat][] & a little of [@rymai][])
19
+
1
20
  ## 0.7.0 - September 14, 2011
2
21
 
3
22
  ## 0.7.0.rc1 - September 5, 2011
@@ -5,7 +24,7 @@
5
24
  ### Major Changes
6
25
 
7
26
  - Posix Signals handlers (`Ctrl-C`, `Ctrl-\` and `Ctrl-Z`) are no more supported and replaced by `$stdin.gets`. Please refer to the "Interactions" section in the README for more information. ([@thibaudgg][])
8
- - JRuby & Rubinius support (beta). ([@thibaudgg][] and [@netzpirat][])
27
+ - JRuby & Rubinius support (beta). ([@thibaudgg][] & [@netzpirat][])
9
28
 
10
29
  ### New feature:
11
30
 
@@ -250,6 +269,7 @@
250
269
  [@fnichol]: https://github.com/fnichol
251
270
  [@Gazer]: https://github.com/Gazer
252
271
  [@gix]: https://github.com/gix
272
+ [@hron]: https://github.com/hron
253
273
  [@hashrocketeer]: https://github.com/hashrocketeer
254
274
  [@ianwhite]: https://github.com/ianwhite
255
275
  [@indirect]: https://github.com/indirect
@@ -257,6 +277,7 @@
257
277
  [@johnbintz]: https://github.com/johnbintz
258
278
  [@jrsacks]: https://github.com/jrsacks
259
279
  [@koshigoe]: https://github.com/koshigoe
280
+ [@limeyd]: https://github.com/limeyd
260
281
  [@mcmire]: https://github.com/mcmire
261
282
  [@mislav]: https://github.com/mislav
262
283
  [@monocle]: https://github.com/monocle
@@ -267,6 +288,7 @@
267
288
  [@niklas]: https://github.com/niklas
268
289
  [@oliamb]: https://github.com/oliamb
269
290
  [@pcreux]: https://github.com/pcreux
291
+ [@rmm5t]: https://github.com/rmm5t
270
292
  [@rymai]: https://github.com/rymai
271
293
  [@stereobooster]: https://github.com/stereobooster
272
294
  [@stouset]: https://github.com/stouset
data/README.md CHANGED
@@ -26,27 +26,19 @@ Install
26
26
 
27
27
  Install the gem:
28
28
 
29
- ``` bash
30
- $ gem install guard
31
- ```
29
+ $ gem install guard
32
30
 
33
31
  Or add it to your Gemfile (inside the `development` group):
34
32
 
35
- ``` ruby
36
- gem 'guard'
37
- ```
33
+ gem 'guard'
38
34
 
39
35
  and install it via Bundler:
40
36
 
41
- ``` bash
42
- $ bundle install
43
- ```
37
+ $ bundle install
44
38
 
45
39
  Generate an empty Guardfile with:
46
40
 
47
- ``` bash
48
- $ guard init
49
- ```
41
+ $ guard init
50
42
 
51
43
  You may optionally place a .Guardfile in your home directory to use it across multiple projects.
52
44
  Also note that if a `.guard.rb` is found in your home directory, it will be appended to the Guardfile.
@@ -57,31 +49,23 @@ Add the guards you need to your Guardfile (see the existing guards below).
57
49
 
58
50
  Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
59
51
 
60
- ``` bash
61
- $ gem install rb-fsevent
62
- ```
52
+ $ gem install rb-fsevent
63
53
 
64
54
  You have two possibilities:
65
55
 
66
56
  Use the [growl_notify gem](https://rubygems.org/gems/growl_notify) (recommended):
67
57
 
68
- ``` bash
69
- $ gem install growl_notify
70
- ```
58
+ $ gem install growl_notify
71
59
 
72
60
  Use the [growlnotify](http://growl.info/extras.php#growlnotify) (cli tool for growl) + the [growl gem](https://rubygems.org/gems/growl).
73
61
 
74
- ``` bash
75
- $ brew install growlnotify
76
- $ gem install growl
77
- ```
62
+ $ brew install growlnotify
63
+ $ gem install growl
78
64
 
79
65
  And add them to your Gemfile:
80
66
 
81
- ``` ruby
82
- gem 'rb-fsevent'
83
- gem 'growl_notify' # or gem 'growl'
84
- ```
67
+ gem 'rb-fsevent'
68
+ gem 'growl_notify' # or gem 'growl'
85
69
 
86
70
  The difference between growl and growl_notify is that growl_notify uses AppleScript to
87
71
  display a message, whereas growl uses the `growlnotify` command. In general the AppleScript
@@ -92,65 +76,47 @@ approach is preferred, but you may also use the older growl gem. Have a look at
92
76
 
93
77
  Install the [rb-inotify gem](https://rubygems.org/gems/rb-inotify) for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
94
78
 
95
- ``` bash
96
- $ gem install rb-inotify
97
- ```
79
+ $ gem install rb-inotify
98
80
 
99
81
  Install the [libnotify gem](https://rubygems.org/gems/libnotify) if you want visual notification support:
100
82
 
101
- ``` bash
102
- $ gem install libnotify
103
- ```
83
+ $ gem install libnotify
104
84
 
105
85
  And add them to your Gemfile:
106
86
 
107
- ``` ruby
108
- gem 'rb-inotify'
109
- gem 'libnotify'
110
- ```
87
+ gem 'rb-inotify'
88
+ gem 'libnotify'
111
89
 
112
90
  ### On Windows
113
91
 
114
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:
115
93
 
116
- ``` bash
117
- $ gem install rb-fchange
118
- ```
94
+ $ gem install rb-fchange
119
95
 
120
96
  Install the [win32console gem](https://rubygems.org/gems/win32console) if you want colors in your terminal:
121
97
 
122
- ``` bash
123
- $ gem install win32console
124
- ```
98
+ $ gem install win32console
125
99
 
126
100
  Install the [rb-notifu gem](https://rubygems.org/gems/rb-notifu) if you want visual notification support:
127
101
 
128
- ``` bash
129
- $ gem install rb-notifu
130
- ```
102
+ $ gem install rb-notifu
131
103
 
132
104
  And add them to your Gemfile:
133
105
 
134
- ``` ruby
135
- gem 'rb-fchange'
136
- gem 'rb-notifu'
137
- gem 'win32console'
138
- ```
106
+ gem 'rb-fchange'
107
+ gem 'rb-notifu'
108
+ gem 'win32console'
139
109
 
140
110
  Usage
141
111
  -----
142
112
 
143
113
  Just launch Guard inside your Ruby / Rails project with:
144
114
 
145
- ``` bash
146
- $ guard [start]
147
- ```
115
+ $ guard [start]
148
116
 
149
117
  or if you use Bundler, to run the Guard executable specific to your bundle:
150
118
 
151
- ``` bash
152
- $ bundle exec guard [start]
153
- ```
119
+ $ bundle exec guard [start]
154
120
 
155
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.
156
122
 
@@ -161,19 +127,15 @@ Command line options
161
127
 
162
128
  Shell can be cleared after each change:
163
129
 
164
- ``` bash
165
- $ guard --clear
166
- $ guard -c # shortcut
167
- ```
130
+ $ guard --clear
131
+ $ guard -c # shortcut
168
132
 
169
133
  ### `-n`/`--notify` option
170
134
 
171
135
  Notifications (growl/libnotify) can be disabled:
172
136
 
173
- ``` bash
174
- $ guard --notify false
175
- $ guard -n f # shortcut
176
- ```
137
+ $ guard --notify false
138
+ $ guard -n f # shortcut
177
139
 
178
140
  Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`
179
141
 
@@ -181,43 +143,42 @@ Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environm
181
143
 
182
144
  Only certain guards groups can be run (see the Guardfile DSL below for creating groups):
183
145
 
184
- ``` bash
185
- $ guard --group group_name another_group_name
186
- $ guard -g group_name another_group_name # shortcut
187
- ```
146
+ $ guard --group group_name another_group_name
147
+ $ guard -g group_name another_group_name # shortcut
188
148
 
189
149
  ### `-d`/`--debug` option
190
150
 
191
151
  Guard can be run in debug mode:
192
152
 
193
- ``` bash
194
- $ guard --debug
195
- $ guard -d # shortcut
196
- ```
153
+ $ guard --debug
154
+ $ guard -d # shortcut
197
155
 
198
156
  ### `-w`/`--watchdir` option
199
157
 
200
158
  Guard can watch in any directory (instead of the current directory):
201
159
 
202
- ``` bash
203
- $ guard --watchdir ~/your/fancy/project
204
- $ guard -w ~/your/fancy/project # shortcut
205
- ```
160
+ $ guard --watchdir ~/your/fancy/project
161
+ $ guard -w ~/your/fancy/project # shortcut
206
162
 
207
163
  ### `-G`/`--guardfile` option
208
164
 
209
165
  Guard can use a Guardfile not located in the current directory:
210
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
+
211
174
  ``` bash
212
- $ guard --guardfile ~/.your_global_guardfile
213
- $ guard -G ~/.your_global_guardfile # shortcut
175
+ $ guard start -A
176
+ $ guard start --watch-all-modifications
214
177
  ```
215
178
 
216
179
  An exhaustive list of options is available with:
217
180
 
218
- ``` bash
219
- $ guard help [TASK]
220
- ```
181
+ $ guard help [TASK]
221
182
 
222
183
  Interactions
223
184
  ------------
@@ -240,21 +201,15 @@ A list of the available guards is present [in the wiki](https://github.com/guard
240
201
 
241
202
  Add it to your Gemfile (inside the `development` group):
242
203
 
243
- ``` ruby
244
- gem '<guard-name>'
245
- ```
204
+ gem '<guard-name>'
246
205
 
247
206
  You can list all guards installed on your system with:
248
207
 
249
- ``` bash
250
- $ guard list
251
- ```
208
+ $ guard list
252
209
 
253
210
  Insert default guard's definition to your Guardfile by running this command:
254
211
 
255
- ``` bash
256
- $ guard init <guard-name>
257
- ```
212
+ $ guard init <guard-name>
258
213
 
259
214
  You are good to go, or you can modify your guards' definition to suit your needs.
260
215
 
@@ -271,36 +226,34 @@ The Guardfile DSL consists of the following methods:
271
226
 
272
227
  Example:
273
228
 
274
- ``` ruby
275
- ignore_paths 'foo', 'bar'
276
-
277
- group 'backend' do
278
- guard 'bundler' do
279
- watch('Gemfile')
280
- end
281
-
282
- guard 'rspec', :cli => '--color --format doc' do
283
- # Regexp watch patterns are matched with Regexp#match
284
- watch(%r{^spec/.+_spec\.rb$})
285
- watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
286
- watch(%r{^spec/models/.+\.rb$}) { ["spec/models", "spec/acceptance"] }
287
- watch(%r{^spec/.+\.rb$}) { `say hello` }
288
-
289
- # String watch patterns are matched with simple '=='
290
- watch('spec/spec_helper.rb') { "spec" }
291
- end
292
- end
293
-
294
- group 'frontend' do
295
- guard 'coffeescript', :output => 'public/javascripts/compiled' do
296
- watch(%r{^app/coffeescripts/.+\.coffee$})
297
- end
298
-
299
- guard 'livereload' do
300
- watch(%r{^app/.+\.(erb|haml)$})
301
- end
302
- end
303
- ```
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
304
257
 
305
258
  Using a Guardfile without the `guard` binary
306
259
  --------------------------------------------
@@ -315,37 +268,33 @@ Remember, without any options given, Guard will look for a Guardfile in your cur
315
268
 
316
269
  For instance, you could use it as follow:
317
270
 
318
- ``` ruby
319
- gem 'guard'
320
- require 'guard'
271
+ gem 'guard'
272
+ require 'guard'
321
273
 
322
- Guard.setup
274
+ Guard.setup
323
275
 
324
- Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
325
- # or
326
- Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
327
- guard 'rspec' do
328
- watch(%r{^spec/.+_spec\.rb$})
329
- end
330
- ")
331
- ```
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
+ ")
332
283
 
333
284
  ### Listing defined guards/groups for the current project
334
285
 
335
286
  You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
336
287
 
337
- ``` bash
338
- # guard -T
339
-
340
- (global):
341
- shell
342
- Group backend:
343
- bundler
344
- rspec: cli => "--color --format doc"
345
- Group frontend:
346
- coffeescript: output => "public/javascripts/compiled"
347
- livereload
348
- ```
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
349
298
 
350
299
  User config file
351
300
  ----------------
@@ -355,114 +304,112 @@ the Guardfile. This can be used for tasks you want guard to handle but
355
304
  other users probably don't. For example, indexing your source tree with
356
305
  [Ctags](http://ctags.sourceforge.net):
357
306
 
358
- ``` ruby
359
- guard 'shell' do
360
- watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
361
- end
362
- ```
307
+ guard 'shell' do
308
+ watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
309
+ end
363
310
 
364
311
  Create a new guard
365
312
  ------------------
366
313
 
367
314
  Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
368
315
 
369
- ```
370
- .travis.yml # bonus point!
371
- CHANGELOG.md # bonus point!
372
- Gemfile
373
- guard-name.gemspec
374
- Guardfile
375
- lib/
376
- guard/
377
- guard-name/
378
- templates/
379
- Guardfile # needed for `guard init <guard-name>`
380
- version.rb
381
- guard-name.rb
382
- test/ # or spec/
383
- README.md
384
- ```
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
385
330
 
386
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.
387
332
 
388
333
  Here is an example scaffold for `lib/guard/guard-name.rb`:
389
334
 
390
- ``` ruby
391
- require 'guard'
392
- require 'guard/guard'
393
-
394
- module Guard
395
- class GuardName < Guard
396
-
397
- def initialize(watchers=[], options={})
398
- super
399
- # init stuff here, thx!
400
- end
401
-
402
- # =================
403
- # = Guard methods =
404
- # =================
405
-
406
- # If one of those methods raise an exception, the Guard::GuardName instance
407
- # will be removed from the active guards.
408
-
409
- # Called once when Guard starts
410
- # Please override initialize method to init stuff
411
- def start
412
- true
413
- end
414
-
415
- # Called on Ctrl-C signal (when Guard quits)
416
- def stop
417
- true
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
418
387
  end
419
388
 
420
- # Called on Ctrl-Z signal
421
- # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
422
- def reload
423
- true
424
- end
425
-
426
- # Called on Ctrl-\ signal
427
- # This method should be principally used for long action like running all specs/tests/...
428
- def run_all
429
- true
430
- end
431
-
432
- # Called on file(s) modifications
433
- def run_on_change(paths)
434
- true
435
- end
436
-
437
- end
438
- end
439
- ```
440
-
441
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.
442
390
 
443
391
  Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
444
392
 
445
- ``` ruby
446
- require 'guard/guard'
393
+ require 'guard/guard'
447
394
 
448
- module ::Guard
449
- class InlineGuard < ::Guard::Guard
450
- def run_all
451
- true
452
- end
395
+ module ::Guard
396
+ class InlineGuard < ::Guard::Guard
397
+ def run_all
398
+ true
399
+ end
453
400
 
454
- def run_on_change(paths)
455
- true
401
+ def run_on_change(paths)
402
+ true
403
+ end
404
+ end
456
405
  end
457
- end
458
- end
459
- ```
460
406
 
461
407
  Here is a very cool example by [@avdi](https://github.com/avdi) : http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis
462
408
 
463
409
  Development
464
410
  -----------
465
411
 
412
+ * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
466
413
  * Source hosted at [GitHub](https://github.com/guard/guard).
467
414
  * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
468
415