Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 460 lines (300 sloc) 15.824 kb
a6d0dab @rymai Use the SSL version of the Travis build image
rymai authored
1 Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png)](http://travis-ci.org/guard/guard)
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
2 =====
3
4 Guard is a command line tool that easily handle events on files modifications.
5
8f7034b @netzpirat Make sure questions go to the Google group/IRC and issues to GitHub.
netzpirat authored
6 If you have any questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
d2af050 Added Google group & irc links in Readme
Thibaud Guillaume-Gentil authored
7
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
8 Features
9 --------
10
11 * [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support on Mac OS X 10.5+ (without RubyCocoa!, [rb-fsevent gem, >= 0.3.5](https://rubygems.org/gems/rb-fsevent) required).
12 * [Inotify](http://en.wikipedia.org/wiki/Inotify) support on Linux ([rb-inotify gem, >= 0.5.1](https://rubygems.org/gems/rb-inotify) required).
057549a @rymai Readme cleanup
rymai authored
13 * [Directory Change Notification](http://msdn.microsoft.com/en-us/library/aa365261\(VS.85\).aspx) support on Windows ([rb-fchange, >= 0.0.2](https://rubygems.org/gems/rb-fchange) required).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
14 * Polling on the other operating systems (help us to support more OS).
15 * Automatic & Super fast (when polling is not used) files modifications detection (even new files are detected).
2769541 @rymai Improve the README
rymai authored
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)).
2edf8be @netzpirat Add JRuby and Rubinius to the list of tested Rubies.
netzpirat authored
17 * Tested against Ruby 1.8.7, 1.9.2, REE and the latest versions of JRuby & Rubinius.
e9cef88 @rymai [ci skip] Added a link to the screencast on Guard by Ryan Bates (idea…
rymai authored
18
19 Screencast
20 ----------
21
a5fb1aa @rymai Forcing some links for Rubydoc.info [ci skip]
rymai authored
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)
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
23
24 Install
25 -------
26
18e0f99 @rymai Added a sentence to tell people to check out the installation instruc…
rymai authored
27
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
28 Install the gem:
29
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
30 $ gem install guard
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
31
2769541 @rymai Improve the README
rymai authored
32 Or add it to your Gemfile (inside the `development` group):
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
33
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
34 gem 'guard'
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
35
2769541 @rymai Improve the README
rymai authored
36 and install it via Bundler:
62ef515 @rymai Oops! [ci skip]
rymai authored
37
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
38 $ bundle install
2769541 @rymai Improve the README
rymai authored
39
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
40 Generate an empty Guardfile with:
41
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
42 $ guard init
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
43
524af46 @tpope Make home Guardfile hidden
tpope authored
44 You may optionally place a .Guardfile in your home directory to use it across multiple projects.
2769541 @rymai Improve the README
rymai authored
45 Also note that if a `.guard.rb` is found in your home directory, it will be appended to the Guardfile.
b69aa76 Update README regarding Guardfile location
Aaron Kalin and Veezus Kreist authored
46
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
47 Add the guards you need to your Guardfile (see the existing guards below).
48
18e0f99 @rymai Added a sentence to tell people to check out the installation instruc…
rymai authored
49 Now, be sure to read the particular instructions for your operating system: [Mac OS X](#mac) | [Linux](#linux) | [Windows](#win)
50
51 <a name="mac" />
50b35cc Fix README for rubydoc [ci skip]
Thibaud Guillaume-Gentil authored
52
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
53 ### On Mac OS X
54
55 Install the rb-fsevent gem for [FSEvent](http://en.wikipedia.org/wiki/FSEvents) support:
56
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
57 $ gem install rb-fsevent
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
58
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
59 You have three possibilities for getting Growl support:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
60
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
61 Use the [growl_notify gem](https://rubygems.org/gems/growl_notify):
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
62
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
63 $ gem install growl_notify
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
64
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
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.
67
68 Use the [ruby_gntp gem](https://github.com/snaka/ruby_gntp):
69
70 $ gem install ruby_gntp
71
95f895e @netzpirat GNTP needs Mac Growl >= 1.3. [ci skip]
netzpirat authored
72 The `ruby_gntp` gem is compatible with Growl >= 1.3 and uses the Growl Notification Transport Protocol to send Growl
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
73 notifications. Guard supports multiple notification channels for customizing each notification type, but it's limited
74 to the local host currently.
75
76 Use the [growl gem](https://rubygems.org/gems/growl):
62ef515 @rymai Oops! [ci skip]
rymai authored
77
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
78 $ gem install growl
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
79
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
80 The `growl` gem is compatible with all versions of Growl and uses a command line tool [growlnotify](http://growl.info/extras.php#growlnotify)
1a45a77 Typo [ci skip]
Thibaud Guillaume-Gentil authored
81 that must be separately downloaded and installed. You can also install it with HomeBrew:
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
82
83 $ brew install growlnotify
84
85 Finally you have to add your Growl library of choice to your Gemfile:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
86
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
87 gem 'rb-fsevent'
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
88 gem 'growl_notify' # or gem 'ruby_gntp' or gem 'growl'
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
89
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
90 Have a look at the [Guard Wiki](https://github.com/guard/guard/wiki/Which-Growl-library-should-I-use) for more information.
0e1564e @netzpirat Revert "remove growl support completely"
netzpirat authored
91
18e0f99 @rymai Added a sentence to tell people to check out the installation instruc…
rymai authored
92 <a name="linux" />
50b35cc Fix README for rubydoc [ci skip]
Thibaud Guillaume-Gentil authored
93
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
94 ### On Linux
95
2769541 @rymai Improve the README
rymai authored
96 Install the [rb-inotify gem](https://rubygems.org/gems/rb-inotify) for [inotify](http://en.wikipedia.org/wiki/Inotify) support:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
97
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
98 $ gem install rb-inotify
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
99
2769541 @rymai Improve the README
rymai authored
100 Install the [libnotify gem](https://rubygems.org/gems/libnotify) if you want visual notification support:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
101
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
102 $ gem install libnotify
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
103
a3c8bbd Updated installation doc
Thibaud Guillaume-Gentil authored
104 And add them to your Gemfile:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
105
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
106 gem 'rb-inotify'
107 gem 'libnotify'
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
108
18e0f99 @rymai Added a sentence to tell people to check out the installation instruc…
rymai authored
109 <a name="win" />
50b35cc Fix README for rubydoc [ci skip]
Thibaud Guillaume-Gentil authored
110
29069cd @stereobooster Update documentation for windows support
stereobooster authored
111 ### On Windows
112
2769541 @rymai Improve the README
rymai authored
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:
29069cd @stereobooster Update documentation for windows support
stereobooster authored
114
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
115 $ gem install rb-fchange
29069cd @stereobooster Update documentation for windows support
stereobooster authored
116
2769541 @rymai Improve the README
rymai authored
117 Install the [win32console gem](https://rubygems.org/gems/win32console) if you want colors in your terminal:
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
118
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
119 $ gem install win32console
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
120
2769541 @rymai Improve the README
rymai authored
121 Install the [rb-notifu gem](https://rubygems.org/gems/rb-notifu) if you want visual notification support:
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
122
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
123 $ gem install rb-notifu
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
124
a3c8bbd Updated installation doc
Thibaud Guillaume-Gentil authored
125 And add them to your Gemfile:
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
126
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
127 gem 'rb-fchange'
128 gem 'rb-notifu'
129 gem 'win32console'
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
130
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
131 Usage
132 -----
133
134 Just launch Guard inside your Ruby / Rails project with:
135
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
136 $ guard [start]
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
137
138 or if you use Bundler, to run the Guard executable specific to your bundle:
139
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
140 $ bundle exec guard [start]
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
141
524af46 @tpope Make home Guardfile hidden
tpope authored
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.
b69aa76 Update README regarding Guardfile location
Aaron Kalin and Veezus Kreist authored
143
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
144 Command line options
145 --------------------
146
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
147 ### `-c`/`--clear` option
d755765 @rymai Improved README
rymai authored
148
149 Shell can be cleared after each change:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
150
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
151 $ guard --clear
152 $ guard -c # shortcut
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
153
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
154 ### `-n`/`--notify` option
d755765 @rymai Improved README
rymai authored
155
156 Notifications (growl/libnotify) can be disabled:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
157
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
158 $ guard --notify false
159 $ guard -n f # shortcut
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
160
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
161 Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`
2f94f9e Fixed notification option
Thibaud Guillaume-Gentil authored
162
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
163 ### `-g`/`--group` option
d755765 @rymai Improved README
rymai authored
164
165 Only certain guards groups can be run (see the Guardfile DSL below for creating groups):
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
166
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
167 $ guard --group group_name another_group_name
168 $ guard -g group_name another_group_name # shortcut
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
169
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
170 ### `-d`/`--debug` option
d755765 @rymai Improved README
rymai authored
171
172 Guard can be run in debug mode:
bbe42f9 @rymai Added informations on the --debug option!
rymai authored
173
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
174 $ guard --debug
175 $ guard -d # shortcut
bbe42f9 @rymai Added informations on the --debug option!
rymai authored
176
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
177 ### `-w`/`--watchdir` option
178
179 Guard can watch in any directory (instead of the current directory):
180
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
181 $ guard --watchdir ~/your/fancy/project
182 $ guard -w ~/your/fancy/project # shortcut
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
183
184 ### `-G`/`--guardfile` option
185
186 Guard can use a Guardfile not located in the current directory:
187
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
188 $ guard --guardfile ~/.your_global_guardfile
189 $ guard -G ~/.your_global_guardfile # shortcut
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
190
0c9634a @limeyd updated README
limeyd authored
191 ### `-A`/`--watch-all-modifications` option
879732f @limeyd updated README with deletions option
limeyd authored
192
479c6b1 Typo
Thibaud Guillaume-Gentil authored
193 Guard can optionally watch all file modifications like moves or deletions with:
423610f @limeyd moved timestamp hash creation into it's own method add initial specs …
limeyd authored
194
50b35cc Fix README for rubydoc [ci skip]
Thibaud Guillaume-Gentil authored
195 $ guard start -A
196 $ guard start --watch-all-modifications
423610f @limeyd moved timestamp hash creation into it's own method add initial specs …
limeyd authored
197
5111e85 Add new cli option
Thibaud Guillaume-Gentil authored
198 ### `-i`/`--no-interactions` option
199
200 Turn off completely any Guard terminal [interactions](#interactions) with:
201
50b35cc Fix README for rubydoc [ci skip]
Thibaud Guillaume-Gentil authored
202 $ guard start -A
203 $ guard start --watch-all-modifications
5111e85 Add new cli option
Thibaud Guillaume-Gentil authored
204
bbe42f9 @rymai Added informations on the --debug option!
rymai authored
205 An exhaustive list of options is available with:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
206
50b35cc Fix README for rubydoc [ci skip]
Thibaud Guillaume-Gentil authored
207 $ guard help [TASK]
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
208
5111e85 Add new cli option
Thibaud Guillaume-Gentil authored
209 <a name="interactions" />
50b35cc Fix README for rubydoc [ci skip]
Thibaud Guillaume-Gentil authored
210
215af07 Replace Signal handlers README section by Interactions
Thibaud Guillaume-Gentil authored
211 Interactions
212 ------------
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
213
3d9d1ad @rymai Make it (even) more clear that `stdin.gets` is only available in the …
rymai authored
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).**
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
215
215af07 Replace Signal handlers README section by Interactions
Thibaud Guillaume-Gentil authored
216 When Guard do nothing you can interact with by entering a command + hitting enter:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
217
215af07 Replace Signal handlers README section by Interactions
Thibaud Guillaume-Gentil authored
218 * `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.
219 * `reload|r|z + enter` - Calls each guard's `#reload` method, in the same order they are declared in the Guardfile.
220 * `pause|p + enter` - Toggle files modification listening. Useful when switching git branches.
221 * `just enter (no commands)` - Calls each guard's `#run_all` method, in the same order they are declared in the Guardfile.
217069b @netzpirat Add wiki link on how to configure signal keyboard shortcuts.
netzpirat authored
222
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
223 Available Guards
224 ----------------
225
c8002ac @rymai Making the README more awesome
rymai authored
226 A list of the available guards is present [in the wiki](https://github.com/guard/guard/wiki/List-of-available-Guards).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
227
228 ### Add a guard to your Guardfile
229
d755765 @rymai Improved README
rymai authored
230 Add it to your Gemfile (inside the `development` group):
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
231
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
232 gem '<guard-name>'
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
233
0054af6 @docwhat Mention 'guard list' in README
docwhat authored
234 You can list all guards installed on your system with:
235
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
236 $ guard list
0054af6 @docwhat Mention 'guard list' in README
docwhat authored
237
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
238 Insert default guard's definition to your Guardfile by running this command:
239
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
240 $ guard init <guard-name>
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
241
d755765 @rymai Improved README
rymai authored
242 You are good to go, or you can modify your guards' definition to suit your needs.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
243
244 Guardfile DSL
245 -------------
246
596f92f @rymai Update README
rymai authored
247 The Guardfile DSL consists of the following methods:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
248
a5fb1aa @rymai Forcing some links for Rubydoc.info [ci skip]
rymai authored
249 * `#guard` - Allows you to add a guard with an optional hash of options.
250 * `#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.
251 * `#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.
252 * `#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.
253 * `#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.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
254
255 Example:
256
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
257 ignore_paths 'foo', 'bar'
258
259 group 'backend' do
260 guard 'bundler' do
261 watch('Gemfile')
262 end
263
264 guard 'rspec', :cli => '--color --format doc' do
265 # Regexp watch patterns are matched with Regexp#match
266 watch(%r{^spec/.+_spec\.rb$})
267 watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
268 watch(%r{^spec/models/.+\.rb$}) { ["spec/models", "spec/acceptance"] }
269 watch(%r{^spec/.+\.rb$}) { `say hello` }
270
271 # String watch patterns are matched with simple '=='
272 watch('spec/spec_helper.rb') { "spec" }
273 end
274 end
275
276 group 'frontend' do
277 guard 'coffeescript', :output => 'public/javascripts/compiled' do
278 watch(%r{^app/coffeescripts/.+\.coffee$})
279 end
280
281 guard 'livereload' do
282 watch(%r{^app/.+\.(erb|haml)$})
283 end
284 end
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
285
596f92f @rymai Update README
rymai authored
286 Using a Guardfile without the `guard` binary
287 --------------------------------------------
c8002ac @rymai Making the README more awesome
rymai authored
288
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
289 The Guardfile DSL can also be used in a programmatic fashion by calling directly `Guard::Dsl.evaluate_guardfile`.
290 Available options are as follow:
291
292 * `:guardfile` - The path to a valid Guardfile.
293 * `:guardfile_contents` - A string representing the content of a valid Guardfile
294
d755765 @rymai Improved README
rymai authored
295 Remember, without any options given, Guard will look for a Guardfile in your current directory and if it does not find one, it will look for it in your `$HOME` directory.
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
296
297 For instance, you could use it as follow:
298
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
299 gem 'guard'
300 require 'guard'
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
301
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
302 Guard.setup
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
303
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
304 Guard::Dsl.evaluate_guardfile(:guardfile => '/your/custom/path/to/a/valid/Guardfile')
305 # or
306 Guard::Dsl.evaluate_guardfile(:guardfile_contents => "
307 guard 'rspec' do
308 watch(%r{^spec/.+_spec\.rb$})
309 end
310 ")
11c3e0b @rymai Keeping the Changelog up to date and improved the Readme
rymai authored
311
7ba4819 @johnbintz documentation and man page updates
johnbintz authored
312 ### Listing defined guards/groups for the current project
313
314 You can list the defined groups and guards for the current Guardfile from the command line using `guard show` or `guard -T`:
315
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
316 $ guard -T
7ba4819 @johnbintz documentation and man page updates
johnbintz authored
317
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
318 (global):
319 shell
320 Group backend:
321 bundler
322 rspec: cli => "--color --format doc"
323 Group frontend:
324 coffeescript: output => "public/javascripts/compiled"
325 livereload
7ba4819 @johnbintz documentation and man page updates
johnbintz authored
326
b59d6ac @tpope Add a user guard config
tpope authored
327 User config file
328 ----------------
329
2769541 @rymai Improve the README
rymai authored
330 If a `.guard.rb` is found in your home directory, it will be appended to
b59d6ac @tpope Add a user guard config
tpope authored
331 the Guardfile. This can be used for tasks you want guard to handle but
332 other users probably don't. For example, indexing your source tree with
333 [Ctags](http://ctags.sourceforge.net):
334
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
335 guard 'shell' do
336 watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
337 end
b59d6ac @tpope Add a user guard config
tpope authored
338
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
339 Create a new guard
340 ------------------
341
057549a @rymai Readme cleanup
rymai authored
342 Creating a new guard is very easy, just create a new gem (`bundle gem` if you use Bundler) with this basic structure:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
343
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
344 .travis.yml # bonus point!
345 CHANGELOG.md # bonus point!
346 Gemfile
347 guard-name.gemspec
348 Guardfile
349 lib/
350 guard/
351 guard-name/
352 templates/
353 Guardfile # needed for `guard init <guard-name>`
354 version.rb
355 guard-name.rb
356 test/ # or spec/
357 README.md
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
358
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
359 `Guard::GuardName` (in `lib/guard/guard-name.rb`) must inherit from
360 [Guard::Guard](http://rubydoc.info/github/guard/guard/master/Guard/Guard) and should overwrite at least one of
361 the basic `Guard::Guard` task methods.
d755765 @rymai Improved README
rymai authored
362
363 Here is an example scaffold for `lib/guard/guard-name.rb`:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
364
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
365 require 'guard'
366 require 'guard/guard'
367
368 module Guard
369 class GuardName < Guard
370
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
371 # Initialize a Guard.
372 # @param [Array<Guard::Watcher>] watchers the Guard file watchers
373 # @param [Hash] options the custom Guard options
309ecc7 @rymai Edited README.md via GitHub
rymai authored
374 def initialize(watchers = [], options = {})
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
375 super
376 end
377
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
378 # Call once when Guard starts. Please override initialize method to init stuff.
379 # @raise [:task_has_failed] when start has failed
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
380 def start
381 end
382
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
383 # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
384 # @raise [:task_has_failed] when stop has failed
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
385 def stop
386 end
387
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
388 # Called when `reload|r|z + enter` is pressed.
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
389 # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
390 # @raise [:task_has_failed] when reload has failed
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
391 def reload
392 end
393
394 # Called when just `enter` is pressed
395 # This method should be principally used for long action like running all specs/tests/...
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
396 # @raise [:task_has_failed] when run_all has failed
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
397 def run_all
398 end
399
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
400 # Called on file(s) modifications that the Guard watches.
401 # @param [Array<String>] paths the changes files or paths
402 # @raise [:task_has_failed] when run_on_change has failed
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
403 def run_on_change(paths)
404 end
405
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
406 # Called on file(s) deletions that the Guard watches.
407 # @param [Array<String>] paths the deleted files or paths
408 # @raise [:task_has_failed] when run_on_change has failed
309ecc7 @rymai Edited README.md via GitHub
rymai authored
409 def run_on_deletion(paths)
410 end
411
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
412 end
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
413 end
414
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
415 Please take a look at the [existing guards' source code](https://github.com/guard/guard/wiki/List-of-available-Guards)
416 for more concrete example and inspiration.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
417
418 Alternatively, a new guard can be added inline to a Guardfile with this basic structure:
419
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
420 require 'guard/guard'
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
421
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
422 module ::Guard
423 class InlineGuard < ::Guard::Guard
424 def run_all
425 end
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
426
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
427 def run_on_change(paths)
428 end
429 end
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
430 end
431
a5fb1aa @rymai Forcing some links for Rubydoc.info [ci skip]
rymai authored
432 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)
d755765 @rymai Improved README
rymai authored
433
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
434 Development
435 -----------
436
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
437 * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
438 * Source hosted at [GitHub](https://github.com/guard/guard).
8f7034b @netzpirat Make sure questions go to the Google group/IRC and issues to GitHub.
netzpirat authored
439 * Report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
440
596f92f @rymai Update README
rymai authored
441 Pull requests are very welcome! Please try to follow these simple "rules", though:
442
443 - Please create a topic branch for every separate change you make;
444 - Make sure your patches are well tested;
445 - Update the README (if applicable);
446 - Update the CHANGELOG (maybe not for a typo but don't hesitate!);
447 - Please **do not change** the version number.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
448
8f7034b @netzpirat Make sure questions go to the Google group/IRC and issues to GitHub.
netzpirat authored
449 For questions please join us on our [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
450
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
451 Author
452 ------
453
ead039b Fixed README
Thibaud Guillaume-Gentil authored
454 [Thibaud Guillaume-Gentil](https://github.com/thibaudgg)
057549a @rymai Readme cleanup
rymai authored
455
456 Contributors
596f92f @rymai Update README
rymai authored
457 ------------
057549a @rymai Readme cleanup
rymai authored
458
a5fb1aa @rymai Forcing some links for Rubydoc.info [ci skip]
rymai authored
459 [https://github.com/guard/guard/contributors](https://github.com/guard/guard/contributors)
Something went wrong with that request. Please try again.