Skip to content
This repository
Newer
Older
100644 364 lines (254 sloc) 9.402 kb
284747be »
2011-05-17 Updated travis-ci png
1 Guard [![Build Status](http://travis-ci.org/guard/guard.png)](http://travis-ci.org/guard/guard)
76df310c »
2011-04-25 README rdoc => markdown
2 =====
3
4 Guard is a command line tool that easily handle events on files modifications.
5
8f7034b8 »
2011-06-10 Make sure questions go to the Google group/IRC and issues to GitHub.
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).
d2af0503 »
2011-06-01 Added Google group & irc links in Readme
7
76df310c »
2011-04-25 README rdoc => markdown
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).
057549a8 »
2011-05-07 Readme cleanup
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).
76df310c »
2011-04-25 README rdoc => markdown
14 * Polling on the other operating systems (help us to support more OS).
15 * Automatic & Super fast (when polling is not used) files modifications detection (even new files are detected).
16 * Growl notifications ([growlnotify](http://growl.info/documentation/growlnotify.php) & [growl gem](https://rubygems.org/gems/growl) required).
17 * Libnotify notifications ([libnotify gem](https://rubygems.org/gems/libnotify) required).
d7394e42 »
2011-05-06 Bye bye 1.8.6 support.
18 * Tested on Ruby 1.8.7, 1.9.2 && ree.
76df310c »
2011-04-25 README rdoc => markdown
19
20 Install
21 -------
22
23 Install the gem:
24
b7137bbf »
2011-05-07 Made the README even more gorgeous!
25 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
26 $ gem install guard
b7137bbf »
2011-05-07 Made the README even more gorgeous!
27 ```
76df310c »
2011-04-25 README rdoc => markdown
28
057549a8 »
2011-05-07 Readme cleanup
29 Add it to your Gemfile (inside the `test` group):
76df310c »
2011-04-25 README rdoc => markdown
30
31 ``` ruby
32 gem 'guard'
33 ```
34
35 Generate an empty Guardfile with:
36
b7137bbf »
2011-05-07 Made the README even more gorgeous!
37 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
38 $ guard init
b7137bbf »
2011-05-07 Made the README even more gorgeous!
39 ```
76df310c »
2011-04-25 README rdoc => markdown
40
b69aa767 »
2011-05-25 Update README regarding Guardfile location
41 You may optionally place this Guardfile in your home directory to use it across multiple projects.
42
76df310c »
2011-04-25 README rdoc => markdown
43 Add the guards you need to your Guardfile (see the existing guards below).
44
45 ### On Mac OS X
46
47 Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
48
b7137bbf »
2011-05-07 Made the README even more gorgeous!
49 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
50 $ gem install rb-fsevent
b7137bbf »
2011-05-07 Made the README even more gorgeous!
51 ```
76df310c »
2011-04-25 README rdoc => markdown
52
53 Install the Growl gem if you want notification support:
54
b7137bbf »
2011-05-07 Made the README even more gorgeous!
55 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
56 $ gem install growl
b7137bbf »
2011-05-07 Made the README even more gorgeous!
57 ```
76df310c »
2011-04-25 README rdoc => markdown
58
a3c8bbd8 »
2011-06-07 Updated installation doc
59 And add them to your Gemfile:
76df310c »
2011-04-25 README rdoc => markdown
60
61 ``` ruby
a3c8bbd8 »
2011-06-07 Updated installation doc
62 gem 'rb-fsevent'
76df310c »
2011-04-25 README rdoc => markdown
63 gem 'growl'
64 ```
65
66 ### On Linux
67
68 Install the rb-inotify gem for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
69
b7137bbf »
2011-05-07 Made the README even more gorgeous!
70 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
71 $ gem install rb-inotify
b7137bbf »
2011-05-07 Made the README even more gorgeous!
72 ```
76df310c »
2011-04-25 README rdoc => markdown
73
74 Install the Libnotify gem if you want notification support:
75
b7137bbf »
2011-05-07 Made the README even more gorgeous!
76 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
77 $ gem install libnotify
b7137bbf »
2011-05-07 Made the README even more gorgeous!
78 ```
76df310c »
2011-04-25 README rdoc => markdown
79
a3c8bbd8 »
2011-06-07 Updated installation doc
80 And add them to your Gemfile:
76df310c »
2011-04-25 README rdoc => markdown
81
82 ``` ruby
a3c8bbd8 »
2011-06-07 Updated installation doc
83 gem 'rb-inotify'
76df310c »
2011-04-25 README rdoc => markdown
84 gem 'libnotify'
85 ```
86
29069cde »
2011-05-07 Update documentation for windows support
87 ### On Windows
88
89 Install the rb-fchange gem for [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support:
90
b7137bbf »
2011-05-07 Made the README even more gorgeous!
91 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
92 $ gem install rb-fchange
b7137bbf »
2011-05-07 Made the README even more gorgeous!
93 ```
29069cde »
2011-05-07 Update documentation for windows support
94
abae416b »
2011-06-07 add Notifu to windows documentation part
95 Install the Notifu gem if you want notification support:
96
97 ``` bash
98 $ gem install rb-notifu
99 ```
100
a3c8bbd8 »
2011-06-07 Updated installation doc
101 And add them to your Gemfile:
abae416b »
2011-06-07 add Notifu to windows documentation part
102
103 ``` ruby
a3c8bbd8 »
2011-06-07 Updated installation doc
104 gem 'rb-fchange'
abae416b »
2011-06-07 add Notifu to windows documentation part
105 gem 'rb-notifu'
106 ```
107
76df310c »
2011-04-25 README rdoc => markdown
108 Usage
109 -----
110
111 Just launch Guard inside your Ruby / Rails project with:
112
b7137bbf »
2011-05-07 Made the README even more gorgeous!
113 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
114 $ guard [start]
b7137bbf »
2011-05-07 Made the README even more gorgeous!
115 ```
76df310c »
2011-04-25 README rdoc => markdown
116
117 or if you use Bundler, to run the Guard executable specific to your bundle:
118
b7137bbf »
2011-05-07 Made the README even more gorgeous!
119 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
120 $ bundle exec guard
b7137bbf »
2011-05-07 Made the README even more gorgeous!
121 ```
76df310c »
2011-04-25 README rdoc => markdown
122
11c3e0b7 »
2011-05-28 Keeping the Changelog up to date and improved the Readme
123 Guard will look for a Guardfile in your current directory. If it does not find one, it will look in your `$HOME` directory for one.
b69aa767 »
2011-05-25 Update README regarding Guardfile location
124
76df310c »
2011-04-25 README rdoc => markdown
125 Command line options
126 --------------------
127
128 Shell can be cleared after each change with:
129
b7137bbf »
2011-05-07 Made the README even more gorgeous!
130 ``` bash
131 $ guard --clear
132 $ guard -c # shortcut
133 ```
76df310c »
2011-04-25 README rdoc => markdown
134
135 Notifications (growl/libnotify) can be disabled with:
136
b7137bbf »
2011-05-07 Made the README even more gorgeous!
137 ``` bash
138 $ guard --notify false
f424854e »
2011-05-10 Refactorized notifier enabling/disabling
139 $ guard -n f # shortcut
b7137bbf »
2011-05-07 Made the README even more gorgeous!
140 ```
76df310c »
2011-04-25 README rdoc => markdown
141
11c3e0b7 »
2011-05-28 Keeping the Changelog up to date and improved the Readme
142 Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`
2f94f9e2 »
2011-05-06 Fixed notification option
143
057549a8 »
2011-05-07 Readme cleanup
144 The guards to start can be specified by group (see the Guardfile DSL below) specifying the `--group` (or `-g`) option:
76df310c »
2011-04-25 README rdoc => markdown
145
b7137bbf »
2011-05-07 Made the README even more gorgeous!
146 ``` bash
147 $ guard --group group_name another_group_name
148 $ guard -g group_name another_group_name # shortcut
149 ```
76df310c »
2011-04-25 README rdoc => markdown
150
151 Options list is available with:
152
b7137bbf »
2011-05-07 Made the README even more gorgeous!
153 ``` bash
6d5cb96e »
2011-05-07 Removed unexpected "`" in README
154 $ guard help [TASK]
b7137bbf »
2011-05-07 Made the README even more gorgeous!
155 ```
76df310c »
2011-04-25 README rdoc => markdown
156
157 Signal handlers
158 ---------------
159
160 Signal handlers are used to interact with Guard:
161
057549a8 »
2011-05-07 Readme cleanup
162 * `Ctrl-C` - Calls each guard's `stop` method, in the same order they are declared in the Guardfile, and then quits Guard itself.
163 * `Ctrl-\` - Calls each guard's `run_all` method, in the same order they are declared in the Guardfile.
164 * `Ctrl-Z` - Calls each guard's `reload` method, in the same order they are declared in the Guardfile.
76df310c »
2011-04-25 README rdoc => markdown
165
217069bb »
2011-05-31 Add wiki link on how to configure signal keyboard shortcuts.
166 You can read more about [configure the signal keyboard shortcuts](https://github.com/guard/guard/wiki/Configure-keyboard-shortcuts) on the wiki.
167
76df310c »
2011-04-25 README rdoc => markdown
168 Available Guards
169 ----------------
170
171 [Available Guards list](https://github.com/guard/guard/wiki/List-of-available-Guards) (on the wiki now)
172
173 ### Add a guard to your Guardfile
174
057549a8 »
2011-05-07 Readme cleanup
175 Add it to your Gemfile (inside the `test` group):
76df310c »
2011-04-25 README rdoc => markdown
176
177 ``` ruby
178 gem '<guard-name>'
179 ```
180
181 Insert default guard's definition to your Guardfile by running this command:
182
b7137bbf »
2011-05-07 Made the README even more gorgeous!
183 ``` bash
184 $ guard init <guard-name>
185 ```
76df310c »
2011-04-25 README rdoc => markdown
186
187 You are good to go!
188
189 Guardfile DSL
190 -------------
191
057549a8 »
2011-05-07 Readme cleanup
192 The Guardfile DSL consists of just three simple methods: `guard`, `watch` & `group`.
76df310c »
2011-04-25 README rdoc => markdown
193
194 Required:
057549a8 »
2011-05-07 Readme cleanup
195
196 * The `guard` method allows you to add a guard with an optional hash of options.
197 * The `watch` method allows you to define which files are supervised by this guard. An optional block can be added to overwrite the paths sent to the `run_on_change` guard method or to launch any arbitrary command.
76df310c »
2011-04-25 README rdoc => markdown
198
199 Optional:
057549a8 »
2011-05-07 Readme cleanup
200
201 * The `group` method allows you to group several guards together. Groups to be run can be specified with the Guard DSL option `--group` (or `-g`). This comes in handy especially when you have a huge Guardfile and want to focus your development on a certain part.
76df310c »
2011-04-25 README rdoc => markdown
202
203 Example:
204
205 ``` ruby
206 group 'backend' do
207 guard 'bundler' do
208 watch('Gemfile')
209 end
210
211 guard 'rspec', :cli => '--color --format doc' do
212 # Regexp watch patterns are matched with Regexp#match
213 watch(%r{^spec/.+_spec\.rb})
214 watch(%r{^lib/(.+)\.rb}) { |m| "spec/lib/#{m[1]}_spec.rb" }
215 watch(%r{^spec/models/.+\.rb}) { ["spec/models", "spec/acceptance"] }
216 watch(%r{^spec/.+\.rb}) { `say hello` }
217
218 # String watch patterns are matched with simple '=='
219 watch('spec/spec_helper.rb') { "spec" }
220 end
221 end
222
223 group 'frontend' do
224 guard 'coffeescript', :output => 'public/javascripts/compiled' do
225 watch(%r{^app/coffeescripts/.+\.coffee})
226 end
227
228 guard 'livereload' do
229 watch(%r{^app/.+\.(erb|haml)})
230 end
231 end
232 ```
233
11c3e0b7 »
2011-05-28 Keeping the Changelog up to date and improved the Readme
234 The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
235 Available options are as follow:
236
237 * `:guardfile` - The path to a valid Guardfile.
238 * `:guardfile_contents` - A string representing the content of a valid Guardfile
239
240 Without any options given, Guard will look for a Guardfile in your current directory and if it does not find one, it will look in your `$HOME` directory for one.
241
242 For instance, you could use it as follow:
243
244 ``` ruby
245 gem 'guard'
246 require 'guard'
247
248 Guard.setup
249
250 Guard::Dsl.evaluate_guardfile(:guardfile => '/Your/Custom/Path/To/A/Valid/Guardfile')
251 # or
252 Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
253 guard 'rspec' do
254 watch(%r{^spec/.+_spec\.rb})
255 end
256 ")
257 ```
258
76df310c »
2011-04-25 README rdoc => markdown
259 Create a new guard
260 ------------------
261
057549a8 »
2011-05-07 Readme cleanup
262 Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
76df310c »
2011-04-25 README rdoc => markdown
263
264 lib/
265 guard/
266 guard-name/
267 templates/
268 Guardfile (needed for guard init <guard-name>)
269 guard-name.rb
270
057549a8 »
2011-05-07 Readme cleanup
271 `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. Example:
76df310c »
2011-04-25 README rdoc => markdown
272
273 ``` ruby
274 require 'guard'
275 require 'guard/guard'
276
277 module Guard
278 class GuardName < Guard
279
280 def initialize(watchers=[], options={})
281 super
282 # init stuff here, thx!
283 end
284
285 # =================
286 # = Guard methods =
287 # =================
288
289 # If one of those methods raise an exception, the Guard::GuardName instance
290 # will be removed from the active guards.
291
292 # Called once when Guard starts
293 # Please override initialize method to init stuff
294 def start
295 true
296 end
297
298 # Called on Ctrl-C signal (when Guard quits)
299 def stop
300 true
301 end
302
303 # Called on Ctrl-Z signal
304 # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
305 def reload
306 true
307 end
308
af7dbb93 »
2011-05-27 Edited README.markdown via GitHub
309 # Called on Ctrl-\ signal
76df310c »
2011-04-25 README rdoc => markdown
310 # This method should be principally used for long action like running all specs/tests/...
311 def run_all
312 true
313 end
314
315 # Called on file(s) modifications
316 def run_on_change(paths)
317 true
318 end
319
320 end
321 end
322 ```
323
324 Please take a look at the existing guards' source code (see the list above) for more concrete example.
325
326 Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
327
328 ``` ruby
329 require 'guard/guard'
330
331 module ::Guard
057549a8 »
2011-05-07 Readme cleanup
332 class InlineGuard < ::Guard::Guard
76df310c »
2011-04-25 README rdoc => markdown
333 def run_all
334 true
335 end
336
337 def run_on_change(paths)
338 true
339 end
340 end
341 end
342 ```
343
344 Development
345 -----------
346
347 * Source hosted at [GitHub](https://github.com/guard/guard).
8f7034b8 »
2011-06-10 Make sure questions go to the Google group/IRC and issues to GitHub.
348 * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
76df310c »
2011-04-25 README rdoc => markdown
349
350 Pull requests are very welcome! Make sure your patches are well tested. Please create a topic branch for every separate change
11c3e0b7 »
2011-05-28 Keeping the Changelog up to date and improved the Readme
351 you make. Please do not change the version in your pull-request.
76df310c »
2011-04-25 README rdoc => markdown
352
8f7034b8 »
2011-06-10 Make sure questions go to the Google group/IRC and issues to GitHub.
353 For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
354
76df310c »
2011-04-25 README rdoc => markdown
355 Author
356 ------
357
ead039b2 »
2011-04-25 Fixed README
358 [Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
057549a8 »
2011-05-07 Readme cleanup
359
360 Contributors
361 ------
362
b69aa767 »
2011-05-25 Update README regarding Guardfile location
363 https://github.com/guard/guard/contributors
Something went wrong with that request. Please try again.