Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 921 lines (653 sloc) 26.215 kb
15d8c1a @netzpirat Move dependency status to the development section.
netzpirat authored
1 Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png?branch=master)](http://travis-ci.org/guard/guard)
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
2 =====
3
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
4 Guard is a command line tool to easily handle events on file system modifications.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
5
77eb27c @netzpirat Add a TOC, polish the file an issue section.
netzpirat authored
6 This document contains a lot of information, please take your time and read these instructions carefully. If you have
7 any questions, ask them in our [Google group](http://groups.google.com/group/guard-dev) or on `#guard`
8 (irc.freenode.net).
9
572b22a @rymai Improve README a bit
rymai authored
10 Before you file an issue, make sure you have read the _[file an issue](#file-an-issue)_ section that contains some
77eb27c @netzpirat Add a TOC, polish the file an issue section.
netzpirat authored
11 important information.
12
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
13 Features
14 --------
15
fe6fc88 Update README
Thibaud Guillaume-Gentil authored
16 * File system changes handled by our awesome [Listen](https://github.com/guard/listen) gem.
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
17 * Support for visual system notifications.
fe6fc88 Update README
Thibaud Guillaume-Gentil authored
18 * Huge ([more than 120](https://rubygems.org/search?query=guard-)) guard extensions eco-system.
a7ff8f1 @netzpirat Remove Rubinius 1.2.4 from Travis.
netzpirat authored
19 * Tested against Ruby 1.8.7, 1.9.2, 1.9.3, 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
20
21 Screencast
22 ----------
23
5f0e380 @netzpirat Changed screencast wording and hide link.
netzpirat authored
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.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
26
7a42fec @netzpirat Pimp the README. [ci skip]
netzpirat authored
27 Installation
28 ------------
29
30 The simplest way to install Guard is to use [Bundler](http://gembundler.com/).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
31
0a22b6d @netzpirat Update installation instructions. [ci skip]
netzpirat authored
32 Add Guard to your `Gemfile`:
18e0f99 @rymai Added a sentence to tell people to check out the installation instruc…
rymai authored
33
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
34 ```ruby
35 group :development do
36 gem 'guard'
37 end
38 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
39
7a42fec @netzpirat Pimp the README. [ci skip]
netzpirat authored
40 and install it by running Bundler:
62ef515 @rymai Oops! [ci skip]
rymai authored
41
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
42 ```bash
43 $ bundle
44 ```
2769541 @rymai Improve the README
rymai authored
45
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
46 Generate an empty `Guardfile` with:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
47
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
48 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
49 $ guard init
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
50 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
51
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
52 If you are using Windows and want colors in your terminal, you'll have to add the
22fa957 @netzpirat Tweak the README.
netzpirat authored
53 [win32console](https://rubygems.org/gems/win32console) gem to your `Gemfile` and install it with Bundler:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
54
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
55 ```ruby
540e583 @netzpirat Do, do, do...
netzpirat authored
56 group :development do
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
57 gem 'win32console'
58 end
59 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
60
a9be057 @netzpirat Running Bundler is important.
netzpirat authored
61 **It's important that you always run Guard through Bundler to avoid errors.** If you're getting sick of typing `bundle exec` all
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
62 the time, try the [Rubygems Bundler](https://github.com/mpapis/rubygems-bundler).
46e5c40 @netzpirat Add Bundler #protip to the README.
netzpirat authored
63
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
64 ### System notifications
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
65
fe9176a @netzpirat Update notification lib section. [ci skip]
netzpirat authored
66 You can configure Guard to make use of the following system notification libraries, but it's strongly recommended
67 to use either Ruby GNTP, Libnotify or Notifu:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
68
2e34275 @netzpirat Add note about the GNTP issue. [ci skip]
netzpirat authored
69 #### Growl
70
71 * Runs on Mac OS X
72 * Supports all [Growl](http://growl.info/) versions
73
74 The [growl](https://rubygems.org/gems/growl) gem is compatible with all versions of Growl and uses a command line tool
75 [growlnotify](http://growl.info/extras.php#growlnotify) that must be separately downloaded and installed. The version of
76 the command line tool must match your Growl version. The `growl` gem does **not** support multiple notification
77 channels.
78
79 You have to download the installer for `growlnotify` from the [Growl download section](http://growl.info/downloads).
80
81 To use `growl` you have to add it to your `Gemfile` and run bundler:
82
83 ```ruby
84 group :development do
85 gem 'growl'
86 end
87 ```
88
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
89 #### Ruby GNTP
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
90
2e34275 @netzpirat Add note about the GNTP issue. [ci skip]
netzpirat authored
91 **There's currently a bug in Growl that prevents displaying the icons through GNTP, see
92 [issue #231](https://github.com/guard/guard/issues/231). Use the growl gem until fixed.**
93
7a42fec @netzpirat Pimp the README. [ci skip]
netzpirat authored
94 * Runs on Mac OS X, Linux and Windows
d223aeb @netzpirat Stay within 120 characters.
netzpirat authored
95 * Supports [Growl](http://growl.info/) version >= 1.3, [Growl for Linux](http://mattn.github.com/growl-for-linux/),
96 [Growl for Windows](http://www.growlforwindows.com/gfw/default.aspx) and
97 [Snarl](https://sites.google.com/site/snarlapp/home)
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
98
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
99 The [ruby_gntp](https://rubygems.org/gems/ruby_gntp) gem sends system notifications over the network with the
100 [Growl Notification Transport Protocol](http://www.growlforwindows.com/gfw/help/gntp.aspx) and supports local and
101 remote notifications.
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
102
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
103 Guard supports multiple notification channels for customizing each notification type. For Growl on Mac OS X you need
104 to have at least version 1.3 installed.
3b0e2ad @netzpirat Add support for Growl Notification Transport Protocol.
netzpirat authored
105
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
106 To use `ruby_gntp` you have to add it to your `Gemfile` and run bundler:
62ef515 @rymai Oops! [ci skip]
rymai authored
107
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
108 ```ruby
540e583 @netzpirat Do, do, do...
netzpirat authored
109 group :development do
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
110 gem 'ruby_gntp'
111 end
112 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
113
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
114 #### Libnotify
50b35cc Fix README for rubydoc [ci skip]
Thibaud Guillaume-Gentil authored
115
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
116 * Runs on Linux, FreeBSD, OpenBSD and Solaris
117 * Supports [Libnotify](http://developer.gnome.org/libnotify/)
29069cd @stereobooster Update documentation for windows support
stereobooster authored
118
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
119 The [libnotify](https://rubygems.org/gems/libnotify) gem supports the Gnome libnotify notification daemon, but it can be
d223aeb @netzpirat Stay within 120 characters.
netzpirat authored
120 used on other window managers as well. You have to install the `libnotify-bin` package with your favorite package
121 manager.
29069cd @stereobooster Update documentation for windows support
stereobooster authored
122
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
123 To use `libnotify` you have to add it to your `Gemfile` and run bundler:
29069cd @stereobooster Update documentation for windows support
stereobooster authored
124
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
125 ```ruby
540e583 @netzpirat Do, do, do...
netzpirat authored
126 group :development do
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
127 gem 'libnotify'
128 end
129 ```
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
130
65e42a8 @alandipert Added notify-send bit to README under libnotify
alandipert authored
131 If you are unable to build the `libnotify` gem on your system, Guard
132 also has a built in notifier - `notifysend` - that shells out to the
133 `notify-send` utility that comes with `libnotify-bin`.
134
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
135 #### Notifu
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
136
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
137 * Runs on Windows
138 * Supports [Notifu](http://www.paralint.com/projects/notifu/)
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
139
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
140 The [rb-notifu](https://rubygems.org/gems/rb-notifu) gem supports Windows system tray notifications.
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
141
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
142 To use `rb-notifu` you have to add it to your `Gemfile` and run bundler:
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
143
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
144 ```ruby
540e583 @netzpirat Do, do, do...
netzpirat authored
145 group :development do
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
146 gem 'rb-notifu'
147 end
148 ```
abae416 @yannlugrin add Notifu to windows documentation part
yannlugrin authored
149
40e6225 @netzpirat Add some notes about growl_notify (Fixes #194)
netzpirat authored
150 #### GrowlNotify
151
152 * Runs on Mac OS X
153 * Supports [Growl](http://growl.info/) version >= 1.3
154 * Doesn't support JRuby and MacRuby.
155 * Doesn't work when forking, e.g. with [Spork](https://github.com/sporkrb/spork).
156
157 The [growl_notify](https://rubygems.org/gems/growl_notify) gem uses AppleScript to send Growl notifications.
158 The gem needs a native C extension to make use of AppleScript and does not run on JRuby and MacRuby.
159
160 Guard supports multiple notification channels for customizing each notification type and you need to have at least
161 Growl version 1.3 installed.
162
163 To use `growl_notify` you have to add it to your `Gemfile` and run bundler:
164
165 ```ruby
166 group :development do
167 gem 'growl_notify'
168 end
169 ```
170
16ab5a8 @netzpirat Create implies that it's new.
netzpirat authored
171 Add more Guards
172 ---------------
f71ee37 @netzpirat Move to section about installing more Guards before the usage section.
netzpirat authored
173
174 Guard is now ready to use and you should add some Guards for your specific use. Start exploring the many Guards
175 available by browsing the [Guard organization](https://github.com/guard) on GitHub or by searching for `guard-` on
176 [RubyGems](https://rubygems.org/search?utf8=%E2%9C%93&query=guard-).
177
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
178 When you have found a Guard of your interest, add it to your `Gemfile`:
f71ee37 @netzpirat Move to section about installing more Guards before the usage section.
netzpirat authored
179
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
180 ```ruby
540e583 @netzpirat Do, do, do...
netzpirat authored
181 group :development do
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
182 gem '<guard-name>'
183 end
184 ```
f71ee37 @netzpirat Move to section about installing more Guards before the usage section.
netzpirat authored
185
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
186 See the init section of the Guard usage below to see how to install the supplied Guard template that you can install and
187 to suit your needs.
188
189 Usage
190 -----
191
192 Guard is run from the command line. Please open your terminal and go to your project work directory.
193
194 ### Help
195
196 You can always get help on the available tasks with the `help` task:
f71ee37 @netzpirat Move to section about installing more Guards before the usage section.
netzpirat authored
197
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
198 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
199 $ guard help
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
200 ```
f71ee37 @netzpirat Move to section about installing more Guards before the usage section.
netzpirat authored
201
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
202 To request more detailed help on a specific task is simple: just appending the task name to the help task.
203 For example, to get help for the `start` task, simply run:
f71ee37 @netzpirat Move to section about installing more Guards before the usage section.
netzpirat authored
204
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
205 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
206 $ guard help start
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
207 ```
f71ee37 @netzpirat Move to section about installing more Guards before the usage section.
netzpirat authored
208
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
209 ### Init
f71ee37 @netzpirat Move to section about installing more Guards before the usage section.
netzpirat authored
210
665813f @Maher4Ever Add documentations for the new behavior of the init task and the bare…
Maher4Ever authored
211 You can generate a Guardfile and have all installed guards be automatically added into
212 it by running the `init` task without any option:
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
213
214 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
215 $ guard init
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
216 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
217
665813f @Maher4Ever Add documentations for the new behavior of the init task and the bare…
Maher4Ever authored
218 You can also specify the name of an installed Guard to only get that Guard
219 in the generated Guardfile:
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
220
221 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
222 $ guard init <guard-name>
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
223 ```
224
665813f @Maher4Ever Add documentations for the new behavior of the init task and the bare…
Maher4Ever authored
225 You can also define your own templates in `~/.guard/templates/` which can be appended in the same way to your existing
4910828 @hawx Added description of new init functionality to README
hawx authored
226 `Guardfile`:
227
228 ```bash
229 $ guard init <template-name>
230 ```
231
665813f @Maher4Ever Add documentations for the new behavior of the init task and the bare…
Maher4Ever authored
232 **Note**: If you already have a `Guardfile` in the current directory, the `init` task can be used
233 to append a supplied Guard template from an installed Guard to your existing
234 `Guardfile`.
235
236 #### `-b`/`--bare` option
237
238 You can generate an empty `Guardfile` by running the `init` task with the bare
239 option:
240
241 ```bash
242 $ guard init --bare
243 $ guard init -b # shortcut
244 ```
245
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
246 ### Start
247
248 Just launch Guard inside your Ruby or Rails project with:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
249
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
250 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
251 $ guard
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
252 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
253
d223aeb @netzpirat Stay within 120 characters.
netzpirat authored
254 Guard will look for a `Guardfile` in your current directory. If it does not find one, it will look in your `$HOME`
255 directory for a `.Guardfile`.
b69aa76 Update README regarding Guardfile location
Aaron Kalin and Veezus Kreist authored
256
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
257 #### `-c`/`--clear` option
d755765 @rymai Improved README
rymai authored
258
af7e532 @netzpirat Be more consistent.
netzpirat authored
259 The shell can be cleared after each change:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
260
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
261 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
262 $ guard --clear
263 $ guard -c # shortcut
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
264 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
265
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
266 #### `-n`/`--notify` option
d755765 @rymai Improved README
rymai authored
267
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
268 System notifications can be disabled:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
269
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
270 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
271 $ guard --notify false
272 $ guard -n f # shortcut
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
273 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
274
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
275 Notifications can also be disabled globally by setting a `GUARD_NOTIFY` environment variable to `false`.
2f94f9e Fixed notification option
Thibaud Guillaume-Gentil authored
276
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
277 #### `-g`/`--group` option
d755765 @rymai Improved README
rymai authored
278
af7e532 @netzpirat Be more consistent.
netzpirat authored
279 Only certain Guard groups can be run:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
280
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
281 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
282 $ guard --group group_name another_group_name
283 $ guard -g group_name another_group_name # shortcut
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
284 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
285
af7e532 @netzpirat Be more consistent.
netzpirat authored
286 See the Guardfile DSL below for creating groups.
287
1d0ae21 @Maher4Ever Replace the verbose option with the debug option
Maher4Ever authored
288 #### `-d`/`--debug` option
d755765 @rymai Improved README
rymai authored
289
1d0ae21 @Maher4Ever Replace the verbose option with the debug option
Maher4Ever authored
290 Guard can display debug information which can be very usefull for plugins
291 developers with:
bbe42f9 @rymai Added informations on the --debug option!
rymai authored
292
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
293 ```bash
1d0ae21 @Maher4Ever Replace the verbose option with the debug option
Maher4Ever authored
294 $ guard --debug
295 $ guard -d # shortcut
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
296 ```
bbe42f9 @rymai Added informations on the --debug option!
rymai authored
297
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
298 #### `-w`/`--watchdir` option
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
299
af7e532 @netzpirat Be more consistent.
netzpirat authored
300 Guard can watch in any directory instead of the current directory:
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
301
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
302 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
303 $ guard --watchdir ~/your/fancy/project
304 $ guard -w ~/your/fancy/project # shortcut
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
305 ```
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
306
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
307 #### `-G`/`--guardfile` option
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
308
7a42fec @netzpirat Pimp the README. [ci skip]
netzpirat authored
309 Guard can use a `Guardfile` not located in the current directory:
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
310
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
311 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
312 $ guard --guardfile ~/.your_global_guardfile
313 $ guard -G ~/.your_global_guardfile # shortcut
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
314 ```
63ca5f0 @rymai [ci skip] Added missing documentation for options and for win32console!
rymai authored
315
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
316 #### `-i`/`--no-interactions` option
5111e85 Add new cli option
Thibaud Guillaume-Gentil authored
317
af7e532 @netzpirat Be more consistent.
netzpirat authored
318 Turn off completely any Guard terminal interactions with:
5111e85 Add new cli option
Thibaud Guillaume-Gentil authored
319
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
320 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
321 $ guard start -i
322 $ guard start --no-interactions
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
323 ```
5111e85 Add new cli option
Thibaud Guillaume-Gentil authored
324
0b43108 Update README.md
Thibaud Guillaume-Gentil authored
325 #### `-B`/`--no-bundler-warning` option
69b8a52 @netzpirat Add a `--no-bundler-warning` option to Guard.
netzpirat authored
326
327 Skip Bundler warning when a Gemfile exists in the project directory but Guard is not run with Bundler.
328
329 ```bash
330 $ guard start -B
331 $ guard start --no-bundler-warning
332 ```
333
061ab9f Add latency and force_polling cli options
Thibaud Guillaume-Gentil authored
334 #### `-l`/`--latency` option
335
472d310 @rymai Improve README and copywriting
rymai authored
336 Overwrite Listen's default latency, useful when your hard-drive / system is slow.
061ab9f Add latency and force_polling cli options
Thibaud Guillaume-Gentil authored
337
338 ```bash
339 $ guard start -l 1.5
340 $ guard start --latency 1.5
341 ```
342
343 #### `-p`/`--force-polling` option
344
345 Force Listen polling listener usage.
346
347 ```bash
348 $ guard start -p
349 $ guard start --force-polling
350 ```
351
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
352 ### List
353
57dbae6 @netzpirat Fix typo. [ci skip]
netzpirat authored
354 You can list the available Guards with the `list` task:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
355
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
356 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
357 $ guard list
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
358
359 Available guards:
360 coffeescript
361 compass
362 cucumber
363 jammit
364 ronn
365 rspec *
366 spork
367 yard
368 See also https://github.com/guard/guard/wiki/List-of-available-Guards
369 * denotes ones already in your Guardfile
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
370 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
371
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
372 ### Show
373
374 You can show the structure of the groups and their Guards with the `show` task:
375
376 ```bash
afa3048 @netzpirat Remove `bundle exec` overdose and add link to Rubygems Bundler.
netzpirat authored
377 $ guard show
f914101 @netzpirat Combine all the Guard usages in the README under a single usage section.
netzpirat authored
378
379 (global):
380 shell
381 Group backend:
382 bundler
383 rspec: cli => "--color --format doc"
384 Group frontend:
385 coffeescript: output => "public/javascripts/compiled"
386 livereload
387 ```
388
389 This shows the internal structure of the evaluated `Guardfile` or `.Guardfile`, with the `.guard.rb` file. You can
390 read more about these files in the shared configuration section below.
391
215af07 Replace Signal handlers README section by Interactions
Thibaud Guillaume-Gentil authored
392 Interactions
393 ------------
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
394
4d2415e @netzpirat Add simple `#gets` based interactor.
netzpirat authored
395 You can interact with Guard and enter commands when Guard has nothing to do. Guard understands the following commands:
64f0b32 New Interactions scope feature:
Thibaud Guillaume-Gentil authored
396
fa2b0ee @netzpirat Testing tab and return characters.
netzpirat authored
397 * `↩`: Run all Guards.
470a48e @netzpirat Show the shortcuts instead of describing it and reorder commands.
netzpirat authored
398 * `h`, `help`: Show a help of the available interactor commands.
399 * `r`, `reload`: Reload all Guards.
400 * `n`, `notification`: Toggle system notifications on and off.
401 * `p`, `pause`: Toggles the file modification listener. The prompt will change to `p>` when paused.
31ccf45 @netzpirat Add some more pause examples (Fixes #255). [ci skip]
netzpirat authored
402 This is useful when switching Git branches, rebase Git or change whitespace.
470a48e @netzpirat Show the shortcuts instead of describing it and reorder commands.
netzpirat authored
403 * `e`, `exit`: Stop all Guards and quit Guard.
3af5d89 @netzpirat Document to new interactor features.
netzpirat authored
404
77fb217 @netzpirat Replace another <enter> with a entity.
netzpirat authored
405 Instead of running all Guards with the `↩` key, you can also run a single Guard by entering its name:
3af5d89 @netzpirat Document to new interactor features.
netzpirat authored
406
407 ```bash
408 > rspec
409 ```
410
411 It's also possible to run all Guards within a group by entering the group name:
412
413 ```bash
414 > frontend
415 ```
416
417 The same applies to Guard reloading. You can reload a Guard with the following command:
418
419 ```bash
420 > ronn reload
421 ```
422
423 This will reload only the Ronn Guard. You can also reload all Guards within a group:
424
425 ```bash
426 > backend reload
427 ```
217069b @netzpirat Add wiki link on how to configure signal keyboard shortcuts.
netzpirat authored
428
4d2415e @netzpirat Add simple `#gets` based interactor.
netzpirat authored
429 ### Readline support
430
431 With Readline enabled, you'll see a command prompt `>` when Guard is ready to accept a command. The command line
432 supports history navigation with the `↑` and `↓` arrow keys, and command auto-completion with the `⇥` key.
433
434 Unfortunately Readline [does not work on MRI](http://bugs.ruby-lang.org/issues/5539) on Mac OS X by default. You can
435 work around the issue by installing a pure Ruby implementation:
436
437 ```ruby
438 platforms :ruby do
439 gem 'rb-readline'
440 end
441 ```
442
443 Guard will automatically enable Readline support if your environment supports it, but you can disable Readline with the
444 `interactor` DSL method or turn off completely with the `--no-interactions` option.
445
7924be5 @netzpirat Merge remote-tracking branch 'steakknife/master'
netzpirat authored
446 ### Signals
447
448 You can also interact with Guard by sending POSIX signals to the Guard process (all but Windows).
449
450 #### Pause watching
451
452 ```bash
453 $ kill -USR1 <guard_pid>
454 ```
455
456 #### Continue watching
457
458 ```bash
459 $ kill -USR2 <guard_pid>
460 ```
461
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
462 Guardfile DSL
463 -------------
464
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
465 The Guardfile DSL is evaluated as plain Ruby, so you can use normal Ruby code in your `Guardfile`.
466 Guard itself provides the following DSL methods that can be used for configuration:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
467
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
468 ### guard
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
469
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
470 The `guard` method allows you to add a Guard to your toolchain and configure it by passing the
471 options after the name of the Guard:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
472
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
473 ```ruby
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
474 guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'
475 ```
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
476
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
477 You can define the same Guard more than once:
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
478
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
479 ```ruby
480 guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'
481 guard :coffeescript, :input => 'specs', :output => 'specs'
482 ```
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
483
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
484 ### watch
485
486 The `watch` method allows you to define which files are watched by a Guard:
487
488 ```ruby
af7e532 @netzpirat Be more consistent.
netzpirat authored
489 guard :bundler do
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
490 watch('Gemfile')
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
491 end
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
492 ```
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
493
7e3c88f @netzpirat Fix typo.
netzpirat authored
494 String watch patterns are matched with [String#==](http://www.ruby-doc.org/core-1.9.2/String.html#method-i-3D-3D).
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
495 You can also pass a regular expression to the watch method:
496
497 ```ruby
498 guard :jessie do
499 watch(%r{^spec/.+(_spec|Spec)\.(js|coffee)})
500 end
501 ```
502
503 This instructs the jessie Guard to watch for file changes in the `spec` folder,
504 but only for file names that ends with `_spec` or `Spec` and have a file type of `js` or `coffee`.
e3b5003 @netzpirat Move comments from the Guardfile example to the DSL section.
netzpirat authored
505
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
506 You can easily test your watcher regular expressions with [Rubular](http://rubular.com/).
507
e3b5003 @netzpirat Move comments from the Guardfile example to the DSL section.
netzpirat authored
508 When you add a block to the watch expression, you can modify the file name that has been
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
509 detected before sending it to the Guard for processing:
510
511 ```ruby
512 guard :rspec do
513 watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
514 end
515 ```
516
517 In this example the regular expression capture group `(.+)` is used to transform a file change
e3b5003 @netzpirat Move comments from the Guardfile example to the DSL section.
netzpirat authored
518 in the `lib` folder to its test case in the `spec` folder. Regular expression watch patterns
519 are matched with [Regexp#match](http://www.ruby-doc.org/core-1.9.2/Regexp.html#method-i-match).
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
520
521 You can also launch any arbitrary command in the supplied block:
522
523 ```ruby
524 guard :shell do
525 watch('.*') { `git status` }
526 end
527 ```
528
529 ### group
530
531 The `group` method allows you to group several Guards together. This comes in handy especially when you
532 have a huge `Guardfile` and want to focus your development on a certain part.
533
534 ```ruby
535 group :specs do
536 guard :rspec do
537 watch(%r{^spec/.+_spec\.rb$})
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
538 end
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
539 end
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
540
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
541 group :docs do
542 guard :ronn do
543 watch(%r{^man/.+\.ronn?$})
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
544 end
545 end
546 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
547
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
548 Groups to be run can be specified with the Guard DSL option `--group` (or `-g`):
549
550 ```bash
551 $ guard -g specs
552 ```
553
554 Guards that don't belong to a group are considered global and are always run.
555
556 ### notification
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
557
7a42fec @netzpirat Pimp the README. [ci skip]
netzpirat authored
558 If you don't specify any notification configuration in your `Guardfile`, Guard goes through the list of available
d223aeb @netzpirat Stay within 120 characters.
netzpirat authored
559 notifiers and takes the first that is available. If you specify your preferred library, auto detection will not take
560 place:
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
561
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
562 ```ruby
563 notification :growl
564 ```
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
565
566 will select the `growl` gem for notifications. You can also set options for a notifier:
567
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
568 ```ruby
569 notification :growl, :sticky => true
570 ```
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
571
572 Each notifier has a slightly different set of supported options:
573
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
574 ```ruby
575 notification :growl, :sticky => true, :host => '192.168.1.5', :password => 'secret'
576 notification :gntp, :sticky => true, :host => '192.168.1.5', :password => 'secret'
577 notification :growl_notify, :sticky => true, :priority => 0
a84501e @viking Add urgency option to libnotify in README
viking authored
578 notification :libnotify, :timeout => 5, :transient => true, :append => false, :urgency => :critical
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
579 notification :notifu, :time => 5, :nosound => true, :xp => true
580 ```
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
581
582 It's possible to use more than one notifier. This allows you to configure different notifiers for different OS if your
583 project is developed cross-platform or if you like to have local and remote notifications.
584
7a42fec @netzpirat Pimp the README. [ci skip]
netzpirat authored
585 Notifications can also be turned off in the `Guardfile`, in addition to setting the environment variable `GUARD_NOTIFY`
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
586 or using the cli switch `-n`:
587
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
588 ```ruby
589 notification :off
590 ```
e2bc789 @netzpirat Add notifications to the README and some more tweaks.
netzpirat authored
591
4d2415e @netzpirat Add simple `#gets` based interactor.
netzpirat authored
592 ### interactor
593
594 You can disable the interactor auto detection and for a specific implementation:
595
596 ```ruby
597 interactor :readline
598 ```
599
600 will select Readline interactor. You can also force the simple interactor without Readline support with:
601
602 ```ruby
603 interactor :simple
604 ```
605
606 If you do not need the keyboard interactions with Guard at all, you can turn them off:
607
608 ```ruby
609 interactor :off
610 ```
611
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
612 ### callback
613
d223aeb @netzpirat Stay within 120 characters.
netzpirat authored
614 The `callback` method allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`,
615 `run_all` and `run_on_change` Guards' method. You can even insert more hooks inside these methods.
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
616
617 ```ruby
af7e532 @netzpirat Be more consistent.
netzpirat authored
618 guard :rspec do
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
619 watch(%r{^spec/.+_spec\.rb$})
620
621 callback(:start_begin) { `mate .` }
622 end
623 ```
624
d223aeb @netzpirat Stay within 120 characters.
netzpirat authored
625 Please see the [hooks and callbacks](https://github.com/guard/guard/wiki/Hooks-and-callbacks) page in the Guard wiki for
626 more details.
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
627
306bd4d Deprecate ignore_paths dsl method
Thibaud Guillaume-Gentil authored
628 ### ignore
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
629
306bd4d Deprecate ignore_paths dsl method
Thibaud Guillaume-Gentil authored
630 The `ignore` method allows you to ignore specific paths. This comes is handy when you have large
631 amounts of non-source data in you project. By default [`.rbx`, `.bundle`, `.git`, `.svn`, `log`, `tmp`, `vendor`](https://github.com/guard/listen/blob/master/lib/listen/directory_record.rb#L14) are ignored.
632 Please note that method only accept regexps. More on the [Listen README](https://github.com/guard/listen#the-patterns-for-filtering-and-ignoring-paths).
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
633
634 ```ruby
306bd4d Deprecate ignore_paths dsl method
Thibaud Guillaume-Gentil authored
635 ignore %r{^ignored/path/}, /public/
636 ```
637
638 ### filter
639
640 The `filter` method allows you to filter specific paths.
641 Please note that method only accept regexps. More on the [Listen README](https://github.com/guard/listen#the-patterns-for-filtering-and-ignoring-paths).
642
643 ```ruby
644 filter /\.txt$/, /.*\.zip/
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
645 ```
646
647 ### Example
648
649 ```ruby
306bd4d Deprecate ignore_paths dsl method
Thibaud Guillaume-Gentil authored
650 ignore %r{^ignored/path/}, /public/
651 filter /\.txt$/, /.*\.zip/
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
652
b5b5559 @netzpirat Make Guardfile example more complex.
netzpirat authored
653 notification :growl_notify
654 notification :gntp, :host => '192.168.1.5'
655
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
656 group :backend do
657 guard :bundler do
658 watch('Gemfile')
659 end
660
661 guard :rspec, :cli => '--color --format doc' do
662 watch(%r{^spec/.+_spec\.rb$})
663 watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
664 watch(%r{^spec/models/.+\.rb$}) { ["spec/models", "spec/acceptance"] }
665 watch(%r{^spec/.+\.rb$}) { `say hello` }
e3b5003 @netzpirat Move comments from the Guardfile example to the DSL section.
netzpirat authored
666 watch('spec/spec_helper.rb') { "spec" }
632a5af @netzpirat Give some love to the DSL section.
netzpirat authored
667 end
668 end
669
670 group :frontend do
671 guard :coffeescript, :output => 'public/javascripts/compiled' do
672 watch(%r{^app/coffeescripts/.+\.coffee$})
673 end
674
675 guard :livereload do
676 watch(%r{^app/.+\.(erb|haml)$})
677 end
678 end
679 ```
680
9e6224e @netzpirat Merge duplicate .guard.rb documentation.
netzpirat authored
681 Shared configurations
682 ---------------------
683
684 You may optionally place a `.Guardfile` in your home directory to use it across multiple projects. It's evaluated when
685 you have no `Guardfile` in your current directory.
686
687 If a `.guard.rb` is found in your home directory, it will be appended to the `Guardfile` in your current directory.
e5cf7d5 @netzpirat Whitespace cleanup
netzpirat authored
688 This can be used for tasks you want guard to handle but other users probably don't.
689
9e6224e @netzpirat Merge duplicate .guard.rb documentation.
netzpirat authored
690 For example, indexing your source tree with [Ctags](http://ctags.sourceforge.net):
691
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
692 ```ruby
b5b5559 @netzpirat Make Guardfile example more complex.
netzpirat authored
693 guard :shell do
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
694 watch(%r{^(?:app|lib)/.+\.rb$}) { `ctags -R` }
695 end
696 ```
d223aeb @netzpirat Stay within 120 characters.
netzpirat authored
697
759ea8f @netzpirat Merge remote-tracking branch 'hedgehog/patch-2' into dev
netzpirat authored
698 Advanced Linux system configuration
699 -----------------------------------
700
bb36d56 @netzpirat Change wording a bit. Avoid unlucky command word wrap. [ci skip]
netzpirat authored
701 It's not uncommon to encounter a system limit on the number of files you can monitor.
702 For example, Ubuntu Lucid's (64bit) inotify limit is set to 8192.
759ea8f @netzpirat Merge remote-tracking branch 'hedgehog/patch-2' into dev
netzpirat authored
703
bb36d56 @netzpirat Change wording a bit. Avoid unlucky command word wrap. [ci skip]
netzpirat authored
704 You can get your current inotify file watch limit by executing:
705
706 ```bash
707 $ cat /proc/sys/fs/inotify/max_user_watches
708 ```
709
710 And set a new limit temporary with:
759ea8f @netzpirat Merge remote-tracking branch 'hedgehog/patch-2' into dev
netzpirat authored
711
712 ```bash
713 sudo sysctl fs.inotify.max_user_watches=524288
714 sudo sysctl -p
715 ```
716
bb36d56 @netzpirat Change wording a bit. Avoid unlucky command word wrap. [ci skip]
netzpirat authored
717 If you like to make your limit permanent, use:
759ea8f @netzpirat Merge remote-tracking branch 'hedgehog/patch-2' into dev
netzpirat authored
718
719 ```bash
bb36d56 @netzpirat Change wording a bit. Avoid unlucky command word wrap. [ci skip]
netzpirat authored
720 echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
759ea8f @netzpirat Merge remote-tracking branch 'hedgehog/patch-2' into dev
netzpirat authored
721 sudo sysctl -p
722 ```
723
724 You may also need to pay attention to the values of `max_queued_events` and `max_user_instances`.
725
16ab5a8 @netzpirat Create implies that it's new.
netzpirat authored
726 Create a Guard
727 --------------
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
728
54ae028 @spadin Removes the usage of the term `guard-name`. `guard-name` was used wit…
spadin authored
729 Creating a new Guard is very easy. For example, to create a Guard named `yoyo` just create a new gem by running `bundle gem guard-yoyo`. Please make your Guard start with `guard-`, so that it can easily be found on RubyGems.
6eb6a0d @netzpirat Polish create a Guard section.
netzpirat authored
730
731 ```bash
54ae028 @spadin Removes the usage of the term `guard-name`. `guard-name` was used wit…
spadin authored
732 $ mkdir guard-yoyo
733 $ cd guard-yoyo
734 $ bundle gem guard-yoyo
6eb6a0d @netzpirat Polish create a Guard section.
netzpirat authored
735 ```
736
737 Now extend the project structure to have an initial Guard:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
738
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
739 ```bash
740 .travis.yml # bonus point!
741 CHANGELOG.md # bonus point!
742 Gemfile
54ae028 @spadin Removes the usage of the term `guard-name`. `guard-name` was used wit…
spadin authored
743 guard-yoyo.gemspec
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
744 Guardfile
745 lib/
746 guard/
54ae028 @spadin Removes the usage of the term `guard-name`. `guard-name` was used wit…
spadin authored
747 yoyo/
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
748 templates/
749 Guardfile # needed for `guard init <guard-name>`
750 version.rb
54ae028 @spadin Removes the usage of the term `guard-name`. `guard-name` was used wit…
spadin authored
751 yoyo.rb
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
752 test/ # or spec/
753 README.md
754 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
755
54ae028 @spadin Removes the usage of the term `guard-name`. `guard-name` was used wit…
spadin authored
756 Your Guard main class `Guard::Yoyo` in `lib/guard/guard-yoyo.rb` must inherit from
5518444 Fix README regarding 1.1 changes
Thibaud Guillaume-Gentil authored
757 [Guard::Guard](http://rubydoc.info/github/guard/guard/master/Guard/Guard) and should implement at least the
758 `#run_on_changes` task method. `#run_on_additions`, `#run_on_modifications` and `#run_on_removals` task methods
759 could be use instead of `#run_on_changes` task method for more control about how changes are handled.
d755765 @rymai Improved README
rymai authored
760
a49181b @spadin Didn't finish updating the section correctly.
spadin authored
761 Here is an example scaffold for `lib/guard/yoyo.rb`:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
762
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
763 ```ruby
764 require 'guard'
765 require 'guard/guard'
766
767 module Guard
a49181b @spadin Didn't finish updating the section correctly.
spadin authored
768 class Yoyo < Guard
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
769
770 # Initialize a Guard.
771 # @param [Array<Guard::Watcher>] watchers the Guard file watchers
772 # @param [Hash] options the custom Guard options
773 def initialize(watchers = [], options = {})
774 super
775 end
776
777 # Call once when Guard starts. Please override initialize method to init stuff.
778 # @raise [:task_has_failed] when start has failed
779 def start
780 end
781
782 # Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
783 # @raise [:task_has_failed] when stop has failed
784 def stop
785 end
786
787 # Called when `reload|r|z + enter` is pressed.
788 # This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
789 # @raise [:task_has_failed] when reload has failed
790 def reload
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
791 end
792
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
793 # Called when just `enter` is pressed
794 # This method should be principally used for long action like running all specs/tests/...
795 # @raise [:task_has_failed] when run_all has failed
796 def run_all
797 end
798
5518444 Fix README regarding 1.1 changes
Thibaud Guillaume-Gentil authored
799 # Default behaviour on file(s) changes that the Guard watches.
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
800 # @param [Array<String>] paths the changes files or paths
801 # @raise [:task_has_failed] when run_on_change has failed
5518444 Fix README regarding 1.1 changes
Thibaud Guillaume-Gentil authored
802 def run_on_changes(paths)
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
803 end
804 end
805 end
806 ```
807
6eb6a0d @netzpirat Polish create a Guard section.
netzpirat authored
808 Please take a look at the source code of some of the [existing Guards](https://github.com/guard)
5bdb56c @netzpirat Update docs regarding :task_has_failed.
netzpirat authored
809 for more concrete example and inspiration.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
810
af7e532 @netzpirat Be more consistent.
netzpirat authored
811 Alternatively, a new Guard can be added inline to a `Guardfile` with this basic structure:
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
812
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
813 ```ruby
814 require 'guard/guard'
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
815
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
816 module ::Guard
817 class InlineGuard < ::Guard::Guard
818 def run_all
819 end
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
820
5518444 Fix README regarding 1.1 changes
Thibaud Guillaume-Gentil authored
821 def run_on_changes(paths)
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
822 end
09ce096 @netzpirat Use redcarpet as markdown engine. Welcome back, colors.
netzpirat authored
823 end
824 end
825 ```
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
826
d223aeb @netzpirat Stay within 120 characters.
netzpirat authored
827 [@avdi](https://github.com/avdi) has a very cool inline Guard example in his blog post
828 [A Guardfile for Redis](http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis).
d755765 @rymai Improved README
rymai authored
829
88a3b36 @netzpirat Reorder section. [ci skip]
netzpirat authored
830 Programmatic use of Guard
831 -------------------------
832
833 The Guardfile DSL can also be used in a programmatic fashion by calling
834 [Guard::Dsl.evaluate_guardfile](http://rubydoc.info/github/guard/guard/master/Guard/Dsl#evaluate_guardfile-class_method).
835
836 Available options are as follow:
837
838 * `:guardfile` - The path to a valid `Guardfile`.
839 * `:guardfile_contents` - A string representing the content of a valid `Guardfile`.
840
841 Remember, without any options given, Guard will look for a `Guardfile` in your current directory and if it does not find
842 one, it will look for it in your `$HOME` directory.
843
844 Evaluate a `Guardfile`:
845
846 ```ruby
847 require 'guard'
848
849 Guard.setup
c0e65e3 @oreoshake Issue 249 - programmatic examples didn't work
oreoshake authored
850 Guard.start(:guardfile => '/path/to/Guardfile')
88a3b36 @netzpirat Reorder section. [ci skip]
netzpirat authored
851 ```
852
853 Evaluate a string as `Guardfile`:
854
855 ```ruby
856 require 'guard'
857
858 Guard.setup
859
860 guardfile = <<-EOF
861 guard 'rspec' do
862 watch(%r{^spec/.+_spec\.rb$})
863 end
864 EOF
865
c0e65e3 @oreoshake Issue 249 - programmatic examples didn't work
oreoshake authored
866 Guard.start(:guardfile_contents => guardfile)
88a3b36 @netzpirat Reorder section. [ci skip]
netzpirat authored
867 ```
868
77eb27c @netzpirat Add a TOC, polish the file an issue section.
netzpirat authored
869 File an issue
870 -------------
dac506e @netzpirat Add a section for filing an issue.
netzpirat authored
871
77eb27c @netzpirat Add a TOC, polish the file an issue section.
netzpirat authored
872 You can report bugs and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
873
874 **Please don't ask question in the issue tracker**, instead ask them in our
875 [Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
876
877 Try to figure out where the issue belongs to: Is it an issue with Guard itself or with a Guard implementation you're
878 using?
dac506e @netzpirat Add a section for filing an issue.
netzpirat authored
879
7303c7c @rymai Tiny typo and anchor name fix.
rymai authored
880 When you file a bug, please try to follow these simple rules if applicable:
dac506e @netzpirat Add a section for filing an issue.
netzpirat authored
881
882 * Make sure you run Guard with `bundle exec` first.
1d0ae21 @Maher4Ever Replace the verbose option with the debug option
Maher4Ever authored
883 * Add debug information to the issue by running Guard with the `--debug` option.
dac506e @netzpirat Add a section for filing an issue.
netzpirat authored
884 * Add your `Guardfile` and `Gemfile` to the issue.
885 * Make sure that the issue is reproducible with your description.
886
03b8e46 @netzpirat Remove surplus asterisk. [ci skip]
netzpirat authored
887 **It's most likely that your bug gets resolved faster if you provide as much information as possible!**
77eb27c @netzpirat Add a TOC, polish the file an issue section.
netzpirat authored
888
665813f @Maher4Ever Add documentations for the new behavior of the init task and the bare…
Maher4Ever authored
889 Development [![Dependency Status](https://gemnasium.com/guard/guard.png?branch=master)](https://gemnasium.com/guard/guard)
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
890 -----------
891
7844863 @netzpirat Remove GitHub flavoured Markdown until rubydoc.info shows the README …
netzpirat authored
892 * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/guard/master/frames).
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
893 * Source hosted at [GitHub](https://github.com/guard/guard).
894
fb92a3f @netzpirat Consistent wording in the issue and development section.
netzpirat authored
895 Pull requests are very welcome! Please try to follow these simple rules if applicable:
596f92f @rymai Update README
rymai authored
896
fb92a3f @netzpirat Consistent wording in the issue and development section.
netzpirat authored
897 * Please create a topic branch for every separate change you make.
ebe97c1 @netzpirat Add hint to `rake spec:portability` to the README. [ci skip]
netzpirat authored
898 * Make sure your patches are well tested. All specs run with `rake spec:portability` must pass.
fb92a3f @netzpirat Consistent wording in the issue and development section.
netzpirat authored
899 * Update the [Yard](http://yardoc.org/) documentation.
572b22a @rymai Improve README a bit
rymai authored
900 * Update the [README](https://github.com/guard/guard/blob/master/README.md).
901 * Update the [CHANGELOG](https://github.com/guard/guard/blob/master/CHANGELOG.md) for noteworthy changes.
fb92a3f @netzpirat Consistent wording in the issue and development section.
netzpirat authored
902 * Please **do not change** the version number.
76df310 README rdoc => markdown
Thibaud Guillaume-Gentil authored
903
d223aeb @netzpirat Stay within 120 characters.
netzpirat authored
904 For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
905 `#guard` (irc.freenode.net).
8f7034b @netzpirat Make sure questions go to the Google group/IRC and issues to GitHub.
netzpirat authored
906
77eb27c @netzpirat Add a TOC, polish the file an issue section.
netzpirat authored
907 ### Author
908
909 [Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](http://twitter.com/thibaudgg))
910
911 ### Core Team
14211e1 Added 'Core Team' section (sorted by first name)
Thibaud Guillaume-Gentil authored
912
4f0459f Add @Maher4Ever to the Core Team!
Thibaud Guillaume-Gentil authored
913 * [Maher Sallam](https://github.com/Maher4Ever) ([@mahersalam](http://twitter.com/mahersalam))
80fd23b @netzpirat Add core team links. [ci skip]
netzpirat authored
914 * [Michael Kessler](https://github.com/netzpirat) ([@netzpirat](http://twitter.com/netzpirat), [mksoft.ch](https://mksoft.ch))
572b22a @rymai Improve README a bit
rymai authored
915 * [Rémy Coutable](https://github.com/rymai) ([@rymai](http://twitter.com/rymai), [rymai.me](http://rymai.me))
80fd23b @netzpirat Add core team links. [ci skip]
netzpirat authored
916 * [Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](http://twitter.com/thibaudgg), [thibaud.me](http://thibaud.me/))
14211e1 Added 'Core Team' section (sorted by first name)
Thibaud Guillaume-Gentil authored
917
77eb27c @netzpirat Add a TOC, polish the file an issue section.
netzpirat authored
918 ### Contributors
057549a @rymai Readme cleanup
rymai authored
919
a08a4d4 @netzpirat Cleanup whitespace.
netzpirat authored
920 [https://github.com/guard/guard/contributors](https://github.com/guard/guard/contributors)
Something went wrong with that request. Please try again.