guard 0.8.8 → 0.9.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.
Files changed (65) hide show
  1. data/CHANGELOG.md +16 -1
  2. data/README.md +665 -293
  3. data/bin/fsevent_watch_guard +0 -0
  4. data/lib/guard.rb +66 -31
  5. data/lib/guard/cli.rb +9 -3
  6. data/lib/guard/dsl.rb +32 -5
  7. data/lib/guard/dsl_describer.rb +3 -2
  8. data/lib/guard/guard.rb +2 -2
  9. data/lib/guard/interactor.rb +179 -48
  10. data/lib/guard/listener.rb +32 -17
  11. data/lib/guard/listeners/darwin.rb +5 -9
  12. data/lib/guard/listeners/linux.rb +6 -10
  13. data/lib/guard/listeners/windows.rb +4 -2
  14. data/lib/guard/notifier.rb +171 -258
  15. data/lib/guard/notifiers/gntp.rb +114 -0
  16. data/lib/guard/notifiers/growl.rb +98 -0
  17. data/lib/guard/notifiers/growl_notify.rb +91 -0
  18. data/lib/guard/notifiers/libnotify.rb +96 -0
  19. data/lib/guard/notifiers/rb_notifu.rb +101 -0
  20. data/lib/guard/ui.rb +2 -2
  21. data/lib/guard/version.rb +1 -1
  22. data/lib/guard/watcher.rb +1 -1
  23. data/lib/vendor/darwin/Gemfile +6 -0
  24. data/lib/vendor/darwin/Guardfile +8 -0
  25. data/lib/vendor/darwin/LICENSE +20 -0
  26. data/lib/vendor/darwin/README.rdoc +254 -0
  27. data/lib/vendor/darwin/Rakefile +21 -0
  28. data/lib/vendor/darwin/ext/extconf.rb +61 -0
  29. data/lib/vendor/darwin/ext/fsevent/fsevent_watch.c +226 -0
  30. data/lib/vendor/darwin/lib/rb-fsevent.rb +2 -0
  31. data/lib/vendor/darwin/lib/rb-fsevent/fsevent.rb +105 -0
  32. data/lib/vendor/darwin/lib/rb-fsevent/version.rb +3 -0
  33. data/lib/vendor/darwin/rb-fsevent.gemspec +24 -0
  34. data/lib/vendor/darwin/spec/fixtures/folder1/file1.txt +0 -0
  35. data/lib/vendor/darwin/spec/fixtures/folder1/folder2/file2.txt +0 -0
  36. data/lib/vendor/darwin/spec/rb-fsevent/fsevent_spec.rb +75 -0
  37. data/lib/vendor/darwin/spec/spec_helper.rb +24 -0
  38. data/lib/vendor/linux/MIT-LICENSE +20 -0
  39. data/lib/vendor/linux/README.md +66 -0
  40. data/lib/vendor/linux/Rakefile +54 -0
  41. data/lib/vendor/linux/VERSION +1 -0
  42. data/lib/vendor/linux/lib/rb-inotify.rb +17 -0
  43. data/lib/vendor/linux/lib/rb-inotify/event.rb +139 -0
  44. data/lib/vendor/linux/lib/rb-inotify/native.rb +31 -0
  45. data/lib/vendor/linux/lib/rb-inotify/native/flags.rb +89 -0
  46. data/lib/vendor/linux/lib/rb-inotify/notifier.rb +308 -0
  47. data/lib/vendor/linux/lib/rb-inotify/watcher.rb +83 -0
  48. data/lib/vendor/linux/rb-inotify.gemspec +53 -0
  49. data/lib/vendor/windows/Gemfile +4 -0
  50. data/lib/vendor/windows/README.md +34 -0
  51. data/lib/vendor/windows/Rakefile +18 -0
  52. data/lib/vendor/windows/lib/rb-fchange.rb +14 -0
  53. data/lib/vendor/windows/lib/rb-fchange/event.rb +29 -0
  54. data/lib/vendor/windows/lib/rb-fchange/native.rb +45 -0
  55. data/lib/vendor/windows/lib/rb-fchange/native/flags.rb +78 -0
  56. data/lib/vendor/windows/lib/rb-fchange/notifier.rb +149 -0
  57. data/lib/vendor/windows/lib/rb-fchange/version.rb +3 -0
  58. data/lib/vendor/windows/lib/rb-fchange/watcher.rb +99 -0
  59. data/lib/vendor/windows/rb-fchange.gemspec +34 -0
  60. data/lib/vendor/windows/spec/fixtures/folder1/file1.txt +0 -0
  61. data/lib/vendor/windows/spec/fixtures/folder1/folder2/file2.txt +0 -0
  62. data/lib/vendor/windows/spec/rb-fchange/fchange_spec.rb +119 -0
  63. data/lib/vendor/windows/spec/spec_helper.rb +21 -0
  64. metadata +87 -22
  65. data/lib/guard/version.rbc +0 -180
@@ -1,3 +1,16 @@
1
+ ## Dev
2
+
3
+ ### Bug fix
4
+
5
+ - [#173](https://github.com/guard/guard/issues/173): Cannot set the watch_all_modifications option. (reported by [@sutherland][], fixed by [@netzpirat][]
6
+ - Fix `guard init` when a guard name is given. ([@rymai][])
7
+
8
+ ### Improvements
9
+
10
+ - [#165](https://github.com/guard/guard/issues/175): Allow underscores in Guard name. ([@benolee][])
11
+ - Add readline support to the interactor. ([@netzpirat][])
12
+ - Add support for notification configuration. ([@netzpirat][])
13
+
1
14
  ## 0.8.8 - October 21, 2011
2
15
 
3
16
  ### Bug fix
@@ -8,7 +21,7 @@
8
21
 
9
22
  ### Bug fix
10
23
 
11
- - [#166](https://github.com/guard/guard/issues/166): Fix silent failure after re-evaluating Guardfile. (reported by [@dgutov][], fixed by [@rymai][], special thanks to [@dyfrgi][] for the [reproductible test case](https://github.com/dyfrgi/Guard-Broken))
24
+ - [#166](https://github.com/guard/guard/issues/166): Fix silent failure after re-evaluating Guardfile. (reported by [@dgutov][], fixed by [@rymai][], special thanks to [@dyfrgi][] for the [reproducible test case](https://github.com/dyfrgi/Guard-Broken))
12
25
 
13
26
  ## 0.8.6 - October 17, 2011
14
27
 
@@ -316,6 +329,7 @@
316
329
  - Added polling listening fallback. ([@thibaudgg][])
317
330
 
318
331
  [@anithri]: https://github.com/anithri
332
+ [@benolee]: https://github.com/benolee
319
333
  [@brainopia]: https://github.com/brainopia
320
334
  [@bronson]: https://github.com/bronson
321
335
  [@capotej]: https://github.com/capotej
@@ -359,6 +373,7 @@
359
373
  [@stereobooster]: https://github.com/stereobooster
360
374
  [@stouset]: https://github.com/stouset
361
375
  [@sunaku]: https://github.com/sunaku
376
+ [@sutherland]: https://github.com/sutherland
362
377
  [@thibaudgg]: https://github.com/thibaudgg
363
378
  [@thierryhenrio]: https://github.com/thierryhenrio
364
379
  [@tinogomes]: https://github.com/tinogomes
data/README.md CHANGED
@@ -1,462 +1,834 @@
1
1
  Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png?branch=master)](http://travis-ci.org/guard/guard)
2
2
  =====
3
3
 
4
- Guard is a command line tool that easily handle events on files modifications.
4
+ Guard is a command line tool to easily handle events on file system modifications.
5
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).
6
+ If you have any questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
7
+ `#guard` (irc.freenode.net).
7
8
 
8
9
  Features
9
10
  --------
10
11
 
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.
12
+ * [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support on Mac OS X.
13
+ * [Inotify](http://en.wikipedia.org/wiki/Inotify) support on Linux.
14
+ * [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support on Windows.
15
+ * Polling on the other operating systems.
16
+ * Automatic and super fast file modification detection when polling is not used.
17
+ Even new and deleted files are detected.
18
+ * Support for visual system notifications.
19
+ * Tested against Ruby 1.8.7, 1.9.2, 1.9.3, REE and the latest versions of JRuby & Rubinius.
18
20
 
19
21
  Screencast
20
22
  ----------
21
23
 
22
- Ryan Bates made a Railscast on Guard, you can view it here: [http://railscasts.com/episodes/264-guard](http://railscasts.com/episodes/264-guard)
24
+ Ryan Bates made an excellent [RailsCast about Guard](http://railscasts.com/episodes/264-guard) and you should definitely
25
+ watch it for a nice introduction to Guard.
23
26
 
24
- Install
25
- -------
27
+ Installation
28
+ ------------
29
+
30
+ The simplest way to install Guard is to use [Bundler](http://gembundler.com/).
26
31
 
27
32
  Add Guard to your `Gemfile`:
28
33
 
29
- group :development do
30
- gem 'guard'
31
- gem 'rb-inotify', :require => false
32
- gem 'rb-fsevent', :require => false
33
- gem 'rb-fchange', :require => false
34
- end
34
+ ```ruby
35
+ group :development do
36
+ gem 'guard'
35
37
 
36
- and install it via Bundler:
38
+ platforms :ruby do
39
+ gem 'rb-readline'
40
+ end
41
+ end
42
+ ```
37
43
 
38
- $ bundle
44
+ and install it by running Bundler:
39
45
 
40
- Generate an empty Guardfile with:
46
+ ```bash
47
+ $ bundle
48
+ ```
41
49
 
42
- $ guard init
50
+ Generate an empty `Guardfile` with:
43
51
 
44
- You may optionally place a .Guardfile in your home directory to use it across multiple projects.
45
- Also note that if a `.guard.rb` is found in your home directory, it will be appended to the Guardfile.
52
+ ```bash
53
+ $ guard init
54
+ ```
46
55
 
47
- Add the guards you need to your Guardfile (see the existing guards below).
56
+ If you are using Windows and want colors in your terminal, you'll have to add the
57
+ [win32console](https://rubygems.org/gems/win32console) gem to your `Gemfile` and install it with Bundler:
48
58
 
49
- Now, be sure to read the particular instructions for your operating system: [Mac OS X](#mac) | [Linux](#linux) | [Windows](#win)
59
+ ```ruby
60
+ group :development do
61
+ gem 'win32console'
62
+ end
63
+ ```
50
64
 
51
- <a name="mac" />
65
+ **It's important that you always run Guard through Bundler to avoid errors.** If you're getting sick of typing `bundle exec` all
66
+ the time, try the [Rubygems Bundler](https://github.com/mpapis/rubygems-bundler).
52
67
 
53
- ### On Mac OS X
68
+ ### System notifications
54
69
 
55
- Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
70
+ You can configure Guard to make use of the following system notification libraries:
56
71
 
57
- $ gem install rb-fsevent
72
+ #### Ruby GNTP
58
73
 
59
- You have three possibilities for getting Growl support:
74
+ * Runs on Mac OS X, Linux and Windows
75
+ * Supports [Growl](http://growl.info/) version >= 1.3, [Growl for Linux](http://mattn.github.com/growl-for-linux/),
76
+ [Growl for Windows](http://www.growlforwindows.com/gfw/default.aspx) and
77
+ [Snarl](https://sites.google.com/site/snarlapp/home)
60
78
 
61
- Use the [growl_notify gem](https://rubygems.org/gems/growl_notify):
79
+ The [ruby_gntp](https://rubygems.org/gems/ruby_gntp) gem sends system notifications over the network with the
80
+ [Growl Notification Transport Protocol](http://www.growlforwindows.com/gfw/help/gntp.aspx) and supports local and
81
+ remote notifications.
62
82
 
63
- $ gem install growl_notify
83
+ Guard supports multiple notification channels for customizing each notification type. For Growl on Mac OS X you need
84
+ to have at least version 1.3 installed.
64
85
 
65
- The `growl_notify` gem is compatible with Growl >= 1.3 and uses AppleScript to send Growl notifications.
66
- The gem needs a native C extension to make use of AppleScript and does not run on JRuby and MacRuby.
86
+ To use `ruby_gntp` you have to add it to your `Gemfile` and run bundler:
67
87
 
68
- Use the [ruby_gntp gem](https://github.com/snaka/ruby_gntp):
88
+ ```ruby
89
+ group :development do
90
+ gem 'ruby_gntp'
91
+ end
92
+ ```
69
93
 
70
- $ gem install ruby_gntp
94
+ #### Growl
71
95
 
72
- The `ruby_gntp` gem is compatible with Growl >= 1.3 and uses the Growl Notification Transport Protocol to send Growl
73
- notifications. Guard supports multiple notification channels for customizing each notification type, but it's limited
74
- to the local host currently.
96
+ * Runs on Mac OS X
97
+ * Supports all [Growl](http://growl.info/) versions
75
98
 
76
- Use the [growl gem](https://rubygems.org/gems/growl):
99
+ The [growl](https://rubygems.org/gems/growl) gem is compatible with all versions of Growl and uses a command line tool
100
+ [growlnotify](http://growl.info/extras.php#growlnotify) that must be separately downloaded and installed. The version of
101
+ the command line tool must match your Growl version. The `growl` gem does **not** support multiple notification
102
+ channels.
77
103
 
78
- $ gem install growl
104
+ You can download an installer for `growlnotify` from the [Growl download section](http://growl.info/downloads) or
105
+ install it with HomeBrew:
79
106
 
80
- The `growl` gem is compatible with all versions of Growl and uses a command line tool [growlnotify](http://growl.info/extras.php#growlnotify)
81
- that must be separately downloaded and installed. You can also install it with HomeBrew:
107
+ ```bash
108
+ $ brew install growlnotify
109
+ ```
82
110
 
83
- $ brew install growlnotify
111
+ To use `growl` you have to add it to your `Gemfile` and run bundler:
84
112
 
85
- Finally you have to add your Growl library of choice to your Gemfile:
113
+ ```ruby
114
+ group :development do
115
+ gem 'growl'
116
+ end
117
+ ```
86
118
 
87
- gem 'rb-fsevent'
88
- gem 'growl_notify' # or gem 'ruby_gntp' or gem 'growl'
119
+ #### Libnotify
89
120
 
90
- Have a look at the [Guard Wiki](https://github.com/guard/guard/wiki/Which-Growl-library-should-I-use) for more information.
121
+ * Runs on Linux, FreeBSD, OpenBSD and Solaris
122
+ * Supports [Libnotify](http://developer.gnome.org/libnotify/)
91
123
 
92
- <a name="linux" />
124
+ The [libnotify](https://rubygems.org/gems/libnotify) gem supports the Gnome libnotify notification daemon, but it can be
125
+ used on other window managers as well. You have to install the `libnotify-bin` package with your favorite package
126
+ manager.
93
127
 
94
- ### On Linux
128
+ To use `libnotify` you have to add it to your `Gemfile` and run bundler:
95
129
 
96
- Install the [rb-inotify gem](https://rubygems.org/gems/rb-inotify) for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
130
+ ```ruby
131
+ group :development do
132
+ gem 'libnotify'
133
+ end
134
+ ```
97
135
 
98
- $ gem install rb-inotify
136
+ #### Notifu
99
137
 
100
- Install the [libnotify gem](https://rubygems.org/gems/libnotify) if you want visual notification support:
138
+ * Runs on Windows
139
+ * Supports [Notifu](http://www.paralint.com/projects/notifu/)
101
140
 
102
- $ gem install libnotify
141
+ The [rb-notifu](https://rubygems.org/gems/rb-notifu) gem supports Windows system tray notifications.
103
142
 
104
- And add them to your Gemfile:
143
+ To use `rb-notifu` you have to add it to your `Gemfile` and run bundler:
105
144
 
106
- gem 'rb-inotify'
107
- gem 'libnotify'
145
+ ```ruby
146
+ group :development do
147
+ gem 'rb-notifu'
148
+ end
149
+ ```
108
150
 
109
- <a name="win" />
151
+ #### GrowlNotify
110
152
 
111
- ### On Windows
153
+ * Runs on Mac OS X
154
+ * Supports [Growl](http://growl.info/) version >= 1.3
155
+ * Doesn't support JRuby and MacRuby.
156
+ * Doesn't work when forking, e.g. with [Spork](https://github.com/sporkrb/spork).
112
157
 
113
- 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:
158
+ The [growl_notify](https://rubygems.org/gems/growl_notify) gem uses AppleScript to send Growl notifications.
159
+ The gem needs a native C extension to make use of AppleScript and does not run on JRuby and MacRuby.
160
+
161
+ Guard supports multiple notification channels for customizing each notification type and you need to have at least
162
+ Growl version 1.3 installed.
114
163
 
115
- $ gem install rb-fchange
164
+ To use `growl_notify` you have to add it to your `Gemfile` and run bundler:
116
165
 
117
- Install the [win32console gem](https://rubygems.org/gems/win32console) if you want colors in your terminal:
166
+ ```ruby
167
+ group :development do
168
+ gem 'growl_notify'
169
+ end
170
+ ```
118
171
 
119
- $ gem install win32console
172
+ Add more Guards
173
+ ---------------
120
174
 
121
- Install the [rb-notifu gem](https://rubygems.org/gems/rb-notifu) if you want visual notification support:
175
+ Guard is now ready to use and you should add some Guards for your specific use. Start exploring the many Guards
176
+ available by browsing the [Guard organization](https://github.com/guard) on GitHub or by searching for `guard-` on
177
+ [RubyGems](https://rubygems.org/search?utf8=%E2%9C%93&query=guard-).
122
178
 
123
- $ gem install rb-notifu
179
+ When you have found a Guard of your interest, add it to your `Gemfile`:
124
180
 
125
- And add them to your Gemfile:
181
+ ```ruby
182
+ group :development do
183
+ gem '<guard-name>'
184
+ end
185
+ ```
126
186
 
127
- gem 'rb-fchange'
128
- gem 'rb-notifu'
129
- gem 'win32console'
187
+ See the init section of the Guard usage below to see how to install the supplied Guard template that you can install and
188
+ to suit your needs.
130
189
 
131
190
  Usage
132
191
  -----
133
192
 
134
- Just launch Guard inside your Ruby / Rails project with:
193
+ Guard is run from the command line. Please open your terminal and go to your project work directory.
194
+
195
+ ### Help
196
+
197
+ You can always get help on the available tasks with the `help` task:
198
+
199
+ ```bash
200
+ $ guard help
201
+ ```
202
+
203
+ To request more detailed help on a specific task is simple: just appending the task name to the help task.
204
+ For example, to get help for the `start` task, simply run:
205
+
206
+ ```bash
207
+ $ guard help start
208
+ ```
209
+
210
+ ### Init
211
+
212
+ You can generate an empty `Guardfile` by running the `init` task:
213
+
214
+ ```bash
215
+ $ guard init
216
+ ```
135
217
 
136
- $ guard [start]
218
+ In addition, the `init` task can be used to append a supplied Guard template from an installed Guard to your existing
219
+ `Guardfile`:
137
220
 
138
- or if you use Bundler, to run the Guard executable specific to your bundle:
221
+ ```bash
222
+ $ guard init <guard-name>
223
+ ```
139
224
 
140
- $ bundle exec guard [start]
225
+ ### Start
141
226
 
142
- 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.
227
+ Just launch Guard inside your Ruby or Rails project with:
143
228
 
144
- Command line options
145
- --------------------
229
+ ```bash
230
+ $ guard
231
+ ```
146
232
 
147
- ### `-c`/`--clear` option
233
+ Guard will look for a `Guardfile` in your current directory. If it does not find one, it will look in your `$HOME`
234
+ directory for a `.Guardfile`.
148
235
 
149
- Shell can be cleared after each change:
236
+ #### `-c`/`--clear` option
150
237
 
151
- $ guard --clear
152
- $ guard -c # shortcut
238
+ The shell can be cleared after each change:
153
239
 
154
- ### `-n`/`--notify` option
240
+ ```bash
241
+ $ guard --clear
242
+ $ guard -c # shortcut
243
+ ```
155
244
 
156
- Notifications (growl/libnotify) can be disabled:
245
+ #### `-n`/`--notify` option
157
246
 
158
- $ guard --notify false
159
- $ guard -n f # shortcut
247
+ System notifications can be disabled:
160
248
 
161
- Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`
249
+ ```bash
250
+ $ guard --notify false
251
+ $ guard -n f # shortcut
252
+ ```
162
253
 
163
- ### `-g`/`--group` option
254
+ Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`.
164
255
 
165
- Only certain guards groups can be run (see the Guardfile DSL below for creating groups):
256
+ #### `-g`/`--group` option
166
257
 
167
- $ guard --group group_name another_group_name
168
- $ guard -g group_name another_group_name # shortcut
258
+ Only certain Guard groups can be run:
169
259
 
170
- ### `-d`/`--debug` option
260
+ ```bash
261
+ $ guard --group group_name another_group_name
262
+ $ guard -g group_name another_group_name # shortcut
263
+ ```
171
264
 
172
- Guard can be run in debug mode:
265
+ See the Guardfile DSL below for creating groups.
173
266
 
174
- $ guard --debug
175
- $ guard -d # shortcut
267
+ #### `-v`/`--verbose` option
176
268
 
177
- ### `-w`/`--watchdir` option
269
+ Guard can be run in verbose mode:
178
270
 
179
- Guard can watch in any directory (instead of the current directory):
271
+ ```bash
272
+ $ guard --verbose
273
+ $ guard -v # shortcut
274
+ ```
180
275
 
181
- $ guard --watchdir ~/your/fancy/project
182
- $ guard -w ~/your/fancy/project # shortcut
276
+ #### `-w`/`--watchdir` option
183
277
 
184
- ### `-G`/`--guardfile` option
278
+ Guard can watch in any directory instead of the current directory:
185
279
 
186
- Guard can use a Guardfile not located in the current directory:
280
+ ```bash
281
+ $ guard --watchdir ~/your/fancy/project
282
+ $ guard -w ~/your/fancy/project # shortcut
283
+ ```
187
284
 
188
- $ guard --guardfile ~/.your_global_guardfile
189
- $ guard -G ~/.your_global_guardfile # shortcut
285
+ #### `-G`/`--guardfile` option
190
286
 
191
- ### `-A`/`--watch-all-modifications` option
287
+ Guard can use a `Guardfile` not located in the current directory:
288
+
289
+ ```bash
290
+ $ guard --guardfile ~/.your_global_guardfile
291
+ $ guard -G ~/.your_global_guardfile # shortcut
292
+ ```
293
+
294
+ #### `-A`/`--watch-all-modifications` option
192
295
 
193
296
  Guard can optionally watch all file modifications like moves or deletions with:
194
297
 
195
- $ guard start -A
196
- $ guard start --watch-all-modifications
298
+ ```bash
299
+ $ guard start -A
300
+ $ guard start --watch-all-modifications
301
+ ```
197
302
 
198
- ### `-i`/`--no-interactions` option
303
+ #### `-i`/`--no-interactions` option
199
304
 
200
- Turn off completely any Guard terminal [interactions](#interactions) with:
305
+ Turn off completely any Guard terminal interactions with:
201
306
 
202
- $ guard start -i
203
- $ guard start --no-interactions
307
+ ```bash
308
+ $ guard start -i
309
+ $ guard start --no-interactions
310
+ ```
204
311
 
205
- An exhaustive list of options is available with:
312
+ ### `-I`/`--no-vendor` option
206
313
 
207
- $ guard help [TASK]
314
+ Ignore the use of vendored gems with:
208
315
 
209
- <a name="interactions" />
316
+ ```bash
317
+ $ guard start -I
318
+ $ guard start --no-vendor
319
+ ```
210
320
 
211
- Interactions
212
- ------------
321
+ ### List
322
+
323
+ You can list the available Guards with the `list` task:
324
+
325
+ ```bash
326
+ $ guard list
327
+
328
+ Available guards:
329
+ coffeescript
330
+ compass
331
+ cucumber
332
+ jammit
333
+ ronn
334
+ rspec *
335
+ spork
336
+ yard
337
+ See also https://github.com/guard/guard/wiki/List-of-available-Guards
338
+ * denotes ones already in your Guardfile
339
+ ```
213
340
 
214
- **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).**
341
+ ### Show
215
342
 
216
- When Guard do nothing you can interact with by entering a command + hitting return/enter:
343
+ You can show the structure of the groups and their Guards with the `show` task:
217
344
 
218
- * `stop`: `stop|quit|exit|s|q|e + return` - Calls each guard's `#stop` method, in the same order they are declared in the Guardfile, and then quits Guard itself.
219
- * `reload`: `reload|r|z + return` - Calls each guard's `#reload` method, in the same order they are declared in the Guardfile.
220
- * `pause`: `pause|p + return` - Toggle files modification listening. Useful when switching git branches.
221
- * `run_all`: `just return (no commands)` - Calls each guard's `#run_all` method, in the same order they are declared in the Guardfile.
345
+ ```bash
346
+ $ guard show
222
347
 
223
- `reload` and `run_all` actions can be scoped to only run on a certain guard or group. Examples:
348
+ (global):
349
+ shell
350
+ Group backend:
351
+ bundler
352
+ rspec: cli => "--color --format doc"
353
+ Group frontend:
354
+ coffeescript: output => "public/javascripts/compiled"
355
+ livereload
356
+ ```
224
357
 
225
- * `backend reload + return` - Call only each guard's `#reload` method on backend group.
226
- * `rspec + return` - Call only rspec guard's `#run_all` method.
358
+ This shows the internal structure of the evaluated `Guardfile` or `.Guardfile`, with the `.guard.rb` file. You can
359
+ read more about these files in the shared configuration section below.
227
360
 
228
- Available Guards
229
- ----------------
361
+ Interactions
362
+ ------------
363
+
364
+ You can interact with Guard and enter commands when Guard has nothing to do. You'll see a command prompt `>` when Guard
365
+ is ready to accept a command. The command line supports history navigation with the `↑` and `↓` arrow keys, and
366
+ command auto-completion with the `⇥` key.
367
+
368
+ You can execute the following commands:
230
369
 
231
- A list of the available guards is present [in the wiki](https://github.com/guard/guard/wiki/List-of-available-Guards).
370
+ * `↩`: Run all Guards.
371
+ * `h`, `help`: Show a help of the available interactor commands.
372
+ * `r`, `reload`: Reload all Guards.
373
+ * `n`, `notification`: Toggle system notifications on and off.
374
+ * `p`, `pause`: Toggles the file modification listener. The prompt will change to `p>` when paused.
375
+ This is useful when switching Git branches.
376
+ * `e`, `exit`: Stop all Guards and quit Guard.
232
377
 
233
- ### Add a guard to your Guardfile
378
+ Instead of running all Guards with the `↩` key, you can also run a single Guard by entering its name:
234
379
 
235
- Add it to your Gemfile (inside the `development` group):
380
+ ```bash
381
+ > rspec
382
+ ```
236
383
 
237
- gem '<guard-name>'
384
+ It's also possible to run all Guards within a group by entering the group name:
238
385
 
239
- You can list all guards installed on your system with:
386
+ ```bash
387
+ > frontend
388
+ ```
240
389
 
241
- $ guard list
390
+ The same applies to Guard reloading. You can reload a Guard with the following command:
242
391
 
243
- Insert default guard's definition to your Guardfile by running this command:
392
+ ```bash
393
+ > ronn reload
394
+ ```
244
395
 
245
- $ guard init <guard-name>
396
+ This will reload only the Ronn Guard. You can also reload all Guards within a group:
246
397
 
247
- You are good to go, or you can modify your guards' definition to suit your needs.
398
+ ```bash
399
+ > backend reload
400
+ ```
248
401
 
249
402
  Guardfile DSL
250
403
  -------------
251
404
 
252
- The Guardfile DSL consists of the following methods:
405
+ The Guardfile DSL is evaluated as plain Ruby, so you can use normal Ruby code in your `Guardfile`.
406
+ Guard itself provides the following DSL methods that can be used for configuration:
253
407
 
254
- * `#guard` - Allows you to add a guard with an optional hash of options.
255
- * `#watch` - Allows you to define which files are supervised by a 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.
256
- * `#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.
257
- * `#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.
258
- * `#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.
408
+ ### guard
259
409
 
260
- Example:
410
+ The `guard` method allows you to add a Guard to your toolchain and configure it by passing the
411
+ options after the name of the Guard:
261
412
 
262
- ignore_paths 'foo', 'bar'
413
+ ```ruby
414
+ guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'
415
+ ```
263
416
 
264
- group 'backend' do
265
- guard 'bundler' do
266
- watch('Gemfile')
267
- end
417
+ You can define the same Guard more than once:
268
418
 
269
- guard 'rspec', :cli => '--color --format doc' do
270
- # Regexp watch patterns are matched with Regexp#match
271
- watch(%r{^spec/.+_spec\.rb$})
272
- watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
273
- watch(%r{^spec/models/.+\.rb$}) { ["spec/models", "spec/acceptance"] }
274
- watch(%r{^spec/.+\.rb$}) { `say hello` }
419
+ ```ruby
420
+ guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'
421
+ guard :coffeescript, :input => 'specs', :output => 'specs'
422
+ ```
275
423
 
276
- # String watch patterns are matched with simple '=='
277
- watch('spec/spec_helper.rb') { "spec" }
278
- end
279
- end
424
+ ### watch
280
425
 
281
- group 'frontend' do
282
- guard 'coffeescript', :output => 'public/javascripts/compiled' do
283
- watch(%r{^app/coffeescripts/.+\.coffee$})
284
- end
426
+ The `watch` method allows you to define which files are watched by a Guard:
285
427
 
286
- guard 'livereload' do
287
- watch(%r{^app/.+\.(erb|haml)$})
288
- end
289
- end
428
+ ```ruby
429
+ guard :bundler do
430
+ watch('Gemfile')
431
+ end
432
+ ```
290
433
 
291
- Using a Guardfile without the `guard` binary
292
- --------------------------------------------
434
+ String watch patterns are matched with [String#==](http://www.ruby-doc.org/core-1.9.2/String.html#method-i-3D-3D).
435
+ You can also pass a regular expression to the watch method:
293
436
 
294
- The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
295
- Available options are as follow:
437
+ ```ruby
438
+ guard :jessie do
439
+ watch(%r{^spec/.+(_spec|Spec)\.(js|coffee)})
440
+ end
441
+ ```
296
442
 
297
- * `:guardfile` - The path to a valid Guardfile.
298
- * `:guardfile_contents` - A string representing the content of a valid Guardfile
443
+ This instructs the jessie Guard to watch for file changes in the `spec` folder,
444
+ but only for file names that ends with `_spec` or `Spec` and have a file type of `js` or `coffee`.
299
445
 
300
- 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.
446
+ You can easily test your watcher regular expressions with [Rubular](http://rubular.com/).
301
447
 
302
- For instance, you could use it as follow:
448
+ When you add a block to the watch expression, you can modify the file name that has been
449
+ detected before sending it to the Guard for processing:
303
450
 
304
- gem 'guard'
305
- require 'guard'
451
+ ```ruby
452
+ guard :rspec do
453
+ watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
454
+ end
455
+ ```
306
456
 
307
- Guard.setup
457
+ In this example the regular expression capture group `(.+)` is used to transform a file change
458
+ in the `lib` folder to its test case in the `spec` folder. Regular expression watch patterns
459
+ are matched with [Regexp#match](http://www.ruby-doc.org/core-1.9.2/Regexp.html#method-i-match).
308
460
 
309
- Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
310
- # or
311
- Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
312
- guard 'rspec' do
313
- watch(%r{^spec/.+_spec\.rb$})
314
- end
315
- ")
461
+ You can also launch any arbitrary command in the supplied block:
316
462
 
317
- ### Listing defined guards/groups for the current project
463
+ ```ruby
464
+ guard :shell do
465
+ watch('.*') { `git status` }
466
+ end
467
+ ```
318
468
 
319
- You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
469
+ ### group
320
470
 
321
- $ guard -T
471
+ The `group` method allows you to group several Guards together. This comes in handy especially when you
472
+ have a huge `Guardfile` and want to focus your development on a certain part.
322
473
 
323
- (global):
324
- shell
325
- Group backend:
326
- bundler
327
- rspec: cli => "--color --format doc"
328
- Group frontend:
329
- coffeescript: output => "public/javascripts/compiled"
330
- livereload
474
+ ```ruby
475
+ group :specs do
476
+ guard :rspec do
477
+ watch(%r{^spec/.+_spec\.rb$})
478
+ end
479
+ end
331
480
 
332
- User config file
333
- ----------------
481
+ group :docs do
482
+ guard :ronn do
483
+ watch(%r{^man/.+\.ronn?$})
484
+ end
485
+ end
486
+ ```
334
487
 
335
- If a `.guard.rb` is found in your home directory, it will be appended to
336
- the Guardfile. This can be used for tasks you want guard to handle but
337
- other users probably don't. For example, indexing your source tree with
338
- [Ctags](http://ctags.sourceforge.net):
488
+ Groups to be run can be specified with the Guard DSL option `--group` (or `-g`):
339
489
 
340
- guard 'shell' do
341
- watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
342
- end
490
+ ```bash
491
+ $ guard -g specs
492
+ ```
493
+
494
+ Guards that don't belong to a group are considered global and are always run.
495
+
496
+ ### notification
497
+
498
+ If you don't specify any notification configuration in your `Guardfile`, Guard goes through the list of available
499
+ notifiers and takes the first that is available. If you specify your preferred library, auto detection will not take
500
+ place:
501
+
502
+ ```ruby
503
+ notification :growl
504
+ ```
505
+
506
+ will select the `growl` gem for notifications. You can also set options for a notifier:
507
+
508
+ ```ruby
509
+ notification :growl, :sticky => true
510
+ ```
511
+
512
+ Each notifier has a slightly different set of supported options:
513
+
514
+ ```ruby
515
+ notification :growl, :sticky => true, :host => '192.168.1.5', :password => 'secret'
516
+ notification :gntp, :sticky => true, :host => '192.168.1.5', :password => 'secret'
517
+ notification :growl_notify, :sticky => true, :priority => 0
518
+ notification :libnotify, :timeout => 5, :transient => true, :append => false
519
+ notification :notifu, :time => 5, :nosound => true, :xp => true
520
+ ```
521
+
522
+ It's possible to use more than one notifier. This allows you to configure different notifiers for different OS if your
523
+ project is developed cross-platform or if you like to have local and remote notifications.
524
+
525
+ Notifications can also be turned off in the `Guardfile`, in addition to setting the environment variable `GUARD_NOTIFY`
526
+ or using the cli switch `-n`:
527
+
528
+ ```ruby
529
+ notification :off
530
+ ```
531
+
532
+ ### callback
533
+
534
+ The `callback` method allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`,
535
+ `run_all` and `run_on_change` Guards' method. You can even insert more hooks inside these methods.
536
+
537
+ ```ruby
538
+ guard :rspec do
539
+ watch(%r{^spec/.+_spec\.rb$})
540
+
541
+ callback(:start_begin) { `mate .` }
542
+ end
543
+ ```
544
+
545
+ Please see the [hooks and callbacks](https://github.com/guard/guard/wiki/Hooks-and-callbacks) page in the Guard wiki for
546
+ more details.
547
+
548
+ ### ignore_paths
549
+
550
+ The `ignore_paths` method allows you to ignore top level directories altogether. This comes is handy when you have large
551
+ amounts of non-source data in you project. By default `.bundle`, `.git`, `log`, `tmp`, and `vendor` are ignored.
552
+ Currently it is only possible to ignore the immediate descendants of the watched directory.
553
+
554
+ ```ruby
555
+ ignore_paths 'public'
556
+ ```
557
+
558
+ ### Example
559
+
560
+ ```ruby
561
+ ignore_paths 'foo', 'bar'
562
+
563
+ notification :growl_notify
564
+ notification :gntp, :host => '192.168.1.5'
565
+
566
+ group :backend do
567
+ guard :bundler do
568
+ watch('Gemfile')
569
+ end
570
+
571
+ guard :rspec, :cli => '--color --format doc' do
572
+ watch(%r{^spec/.+_spec\.rb$})
573
+ watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
574
+ watch(%r{^spec/models/.+\.rb$}) { ["spec/models", "spec/acceptance"] }
575
+ watch(%r{^spec/.+\.rb$}) { `say hello` }
576
+ watch('spec/spec_helper.rb') { "spec" }
577
+ end
578
+ end
579
+
580
+ group :frontend do
581
+ guard :coffeescript, :output => 'public/javascripts/compiled' do
582
+ watch(%r{^app/coffeescripts/.+\.coffee$})
583
+ end
584
+
585
+ guard :livereload do
586
+ watch(%r{^app/.+\.(erb|haml)$})
587
+ end
588
+ end
589
+ ```
343
590
 
344
- Create a new guard
345
- ------------------
346
-
347
- Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
348
-
349
- .travis.yml # bonus point!
350
- CHANGELOG.md # bonus point!
351
- Gemfile
352
- guard-name.gemspec
353
- Guardfile
354
- lib/
355
- guard/
356
- guard-name/
357
- templates/
358
- Guardfile # needed for `guard init <guard-name>`
359
- version.rb
360
- guard-name.rb
361
- test/ # or spec/
362
- README.md
363
-
364
- `Guard::GuardName` (in `lib/guard/guard-name.rb`) must inherit from
365
- [Guard::Guard](http://rubydoc.info/github/guard/guard/master/Guard/Guard) and should overwrite at least one of
366
- the basic `Guard::Guard` task methods.
591
+ Shared configurations
592
+ ---------------------
593
+
594
+ You may optionally place a `.Guardfile` in your home directory to use it across multiple projects. It's evaluated when
595
+ you have no `Guardfile` in your current directory.
596
+
597
+ If a `.guard.rb` is found in your home directory, it will be appended to the `Guardfile` in your current directory.
598
+ This can be used for tasks you want guard to handle but other users probably don't.
599
+
600
+ For example, indexing your source tree with [Ctags](http://ctags.sourceforge.net):
601
+
602
+ ```ruby
603
+ guard :shell do
604
+ watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
605
+ end
606
+ ```
607
+
608
+ Advanced Linux system configuration
609
+ -----------------------------------
610
+
611
+ It's not uncommon to encounter a system limit on the number of files you can monitor.
612
+ For example, Ubuntu Lucid's (64bit) inotify limit is set to 8192.
613
+
614
+ You can get your current inotify file watch limit by executing:
615
+
616
+ ```bash
617
+ $ cat /proc/sys/fs/inotify/max_user_watches
618
+ ```
619
+
620
+ And set a new limit temporary with:
621
+
622
+ ```bash
623
+ sudo sysctl fs.inotify.max_user_watches=524288
624
+ sudo sysctl -p
625
+ ```
626
+
627
+ If you like to make your limit permanent, use:
628
+
629
+ ```bash
630
+ echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
631
+ sudo sysctl -p
632
+ ```
633
+
634
+ You may also need to pay attention to the values of `max_queued_events` and `max_user_instances`.
635
+
636
+ Create a Guard
637
+ --------------
638
+
639
+ Creating a new Guard is very easy, just create a new gem by running `bundle gem guard-name`, where `name` is
640
+ the name of your Guard. Please make your Guard start with `guard-`, so that it can easily be found on RubyGems.
641
+
642
+ ```bash
643
+ $ mkdir guard-name
644
+ $ cd guard-name
645
+ $ bundle gem guard-name
646
+ ```
647
+
648
+ Now extend the project structure to have an initial Guard:
649
+
650
+ ```bash
651
+ .travis.yml # bonus point!
652
+ CHANGELOG.md # bonus point!
653
+ Gemfile
654
+ guard-name.gemspec
655
+ Guardfile
656
+ lib/
657
+ guard/
658
+ guard-name/
659
+ templates/
660
+ Guardfile # needed for `guard init <guard-name>`
661
+ version.rb
662
+ guard-name.rb
663
+ test/ # or spec/
664
+ README.md
665
+ ```
666
+
667
+ Your Guard main class `Guard::GuardName` in `lib/guard/guard-name.rb` must inherit from
668
+ [Guard::Guard](http://rubydoc.info/github/guard/guard/master/Guard/Guard) and should overwrite at least the
669
+ `#run_on_change` task methods.
367
670
 
368
671
  Here is an example scaffold for `lib/guard/guard-name.rb`:
369
672
 
370
- require 'guard'
371
- require 'guard/guard'
372
-
373
- module Guard
374
- class GuardName < Guard
375
-
376
- # Initialize a Guard.
377
- # @param [Array<Guard::Watcher>] watchers the Guard file watchers
378
- # @param [Hash] options the custom Guard options
379
- def initialize(watchers = [], options = {})
380
- super
381
- end
382
-
383
- # Call once when Guard starts. Please override initialize method to init stuff.
384
- # @raise [:task_has_failed] when start has failed
385
- def start
386
- end
387
-
388
- # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
389
- # @raise [:task_has_failed] when stop has failed
390
- def stop
391
- end
392
-
393
- # Called when `reload|r|z + enter` is pressed.
394
- # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
395
- # @raise [:task_has_failed] when reload has failed
396
- def reload
397
- end
398
-
399
- # Called when just `enter` is pressed
400
- # This method should be principally used for long action like running all specs/tests/...
401
- # @raise [:task_has_failed] when run_all has failed
402
- def run_all
403
- end
404
-
405
- # Called on file(s) modifications that the Guard watches.
406
- # @param [Array<String>] paths the changes files or paths
407
- # @raise [:task_has_failed] when run_on_change has failed
408
- def run_on_change(paths)
409
- end
410
-
411
- # Called on file(s) deletions that the Guard watches.
412
- # @param [Array<String>] paths the deleted files or paths
413
- # @raise [:task_has_failed] when run_on_change has failed
414
- def run_on_deletion(paths)
415
- end
416
-
417
- end
673
+ ```ruby
674
+ require 'guard'
675
+ require 'guard/guard'
676
+
677
+ module Guard
678
+ class GuardName < Guard
679
+
680
+ # Initialize a Guard.
681
+ # @param [Array<Guard::Watcher>] watchers the Guard file watchers
682
+ # @param [Hash] options the custom Guard options
683
+ def initialize(watchers = [], options = {})
684
+ super
685
+ end
686
+
687
+ # Call once when Guard starts. Please override initialize method to init stuff.
688
+ # @raise [:task_has_failed] when start has failed
689
+ def start
690
+ end
691
+
692
+ # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
693
+ # @raise [:task_has_failed] when stop has failed
694
+ def stop
695
+ end
696
+
697
+ # Called when `reload|r|z + enter` is pressed.
698
+ # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
699
+ # @raise [:task_has_failed] when reload has failed
700
+ def reload
701
+ end
702
+
703
+ # Called when just `enter` is pressed
704
+ # This method should be principally used for long action like running all specs/tests/...
705
+ # @raise [:task_has_failed] when run_all has failed
706
+ def run_all
418
707
  end
419
708
 
420
- Please take a look at the [existing guards' source code](https://github.com/guard/guard/wiki/List-of-available-Guards)
709
+ # Called on file(s) modifications that the Guard watches.
710
+ # @param [Array<String>] paths the changes files or paths
711
+ # @raise [:task_has_failed] when run_on_change has failed
712
+ def run_on_change(paths)
713
+ end
714
+
715
+ # Called on file(s) deletions that the Guard watches.
716
+ # @param [Array<String>] paths the deleted files or paths
717
+ # @raise [:task_has_failed] when run_on_change has failed
718
+ def run_on_deletion(paths)
719
+ end
720
+
721
+ end
722
+ end
723
+ ```
724
+
725
+ Please take a look at the source code of some of the [existing Guards](https://github.com/guard)
421
726
  for more concrete example and inspiration.
422
727
 
423
- Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
728
+ Alternatively, a new Guard can be added inline to a `Guardfile` with this basic structure:
424
729
 
425
- require 'guard/guard'
730
+ ```ruby
731
+ require 'guard/guard'
426
732
 
427
- module ::Guard
428
- class InlineGuard < ::Guard::Guard
429
- def run_all
430
- end
733
+ module ::Guard
734
+ class InlineGuard < ::Guard::Guard
735
+ def run_all
736
+ end
431
737
 
432
- def run_on_change(paths)
433
- end
434
- end
738
+ def run_on_change(paths)
435
739
  end
740
+ end
741
+ end
742
+ ```
743
+
744
+ [@avdi](https://github.com/avdi) has a very cool inline Guard example in his blog post
745
+ [A Guardfile for Redis](http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis).
746
+
747
+ Programmatic use of Guard
748
+ -------------------------
749
+
750
+ The Guardfile DSL can also be used in a programmatic fashion by calling
751
+ [Guard::Dsl.evaluate_guardfile](http://rubydoc.info/github/guard/guard/master/Guard/Dsl#evaluate_guardfile-class_method).
752
+
753
+ Available options are as follow:
754
+
755
+ * `:guardfile` - The path to a valid `Guardfile`.
756
+ * `:guardfile_contents` - A string representing the content of a valid `Guardfile`.
757
+
758
+ Remember, without any options given, Guard will look for a `Guardfile` in your current directory and if it does not find
759
+ one, it will look for it in your `$HOME` directory.
760
+
761
+ Evaluate a `Guardfile`:
436
762
 
437
- Here is a very cool example by [@avdi](https://github.com/avdi) : [http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis](http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis)
763
+ ```ruby
764
+ require 'guard'
765
+
766
+ Guard.setup
767
+ Guard::Dsl.evaluate_guardfile(:guardfile => '/path/to/Guardfile')
768
+ Guard.start
769
+ ```
770
+
771
+ Evaluate a string as `Guardfile`:
772
+
773
+ ```ruby
774
+ require 'guard'
775
+
776
+ Guard.setup
777
+
778
+ guardfile = <<-EOF
779
+ guard 'rspec' do
780
+ watch(%r{^spec/.+_spec\.rb$})
781
+ end
782
+ EOF
783
+
784
+ Guard::Dsl.evaluate_guardfile(:guardfile_contents => guardfile)
785
+ Guard.start
786
+ ```
787
+
788
+ Issues
789
+ ------
790
+
791
+ You can report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues). Try to figure out
792
+ where the issue belongs to: Is it an issue with Guard itself or with a Guard implementation you're using? Please don't
793
+ ask question in the issue tracker, instead join us in our [Google group](http://groups.google.com/group/guard-dev) or on
794
+ `#guard` (irc.freenode.net).
795
+
796
+ When you file an issue, please try to follow to these simple rules if applicable:
797
+
798
+ * Make sure you run Guard with `bundle exec` first.
799
+ * Add verbose information to the issue by running Guard with the `--verbose` option.
800
+ * Add your `Guardfile` and `Gemfile` to the issue.
801
+ * Make sure that the issue is reproducible with your description.
438
802
 
439
803
  Development
440
804
  -----------
441
805
 
442
806
  * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
443
807
  * Source hosted at [GitHub](https://github.com/guard/guard).
444
- * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
445
808
 
446
- Pull requests are very welcome! Please try to follow these simple "rules", though:
809
+ Pull requests are very welcome! Please try to follow these simple rules if applicable:
810
+
811
+ * Please create a topic branch for every separate change you make.
812
+ * Make sure your patches are well tested. All specs run with `rake spec:portability` must pass.
813
+ * Update the [Yard](http://yardoc.org/) documentation.
814
+ * Update the README.
815
+ * Update the CHANGELOG for noteworthy changes.
816
+ * Please **do not change** the version number.
817
+
818
+ For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
819
+ `#guard` (irc.freenode.net).
447
820
 
448
- - Please create a topic branch for every separate change you make;
449
- - Make sure your patches are well tested;
450
- - Update the README (if applicable);
451
- - Update the CHANGELOG (maybe not for a typo but don't hesitate!);
452
- - Please **do not change** the version number.
821
+ Core Team
822
+ ---------
453
823
 
454
- For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
824
+ * [Michael Kessler](https://github.com/netzpirat) ([@netzpirat](http://twitter.com/netzpirat))
825
+ * [Rémy Coutable](https://github.com/rymai) ([@rymai](http://twitter.com/rymai))
826
+ * [Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](http://twitter.com/thibaudgg))
455
827
 
456
828
  Author
457
829
  ------
458
830
 
459
- [Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
831
+ [Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](http://twitter.com/thibaudgg))
460
832
 
461
833
  Contributors
462
834
  ------------