Permalink
Browse files

Add a TOC, polish the file an issue section.

  • Loading branch information...
1 parent 69b8a52 commit 77eb27c301fc186070648daa0b6b3e37c6f1591c @netzpirat netzpirat committed Mar 12, 2012
Showing with 84 additions and 18 deletions.
  1. +84 −18 README.md
View
102 README.md
@@ -3,9 +3,46 @@ Guard [![Build Status](https://secure.travis-ci.org/guard/guard.png?branch=maste
Guard is a command line tool to easily handle events on file system modifications.
-If you have any questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
-`#guard` (irc.freenode.net).
+This document contains a lot of information, please take your time and read these instructions carefully. If you have
+any questions, ask them in our [Google group](http://groups.google.com/group/guard-dev) or on `#guard`
+(irc.freenode.net).
+
+Before you file an issue, make sure you have read the [file an issue](#reporting-issues) section that contains some
+important information.
+
+Contents
+--------
+* [Features](#features)
+* [Screencast](#screencast)
+* [Installation](#installation)
+ * [System notifications](#installation-system-notifications)
+* [Add more Guards](#add-more-guards)
+* [Usage](#usage)
+ * [Help](#usage-help)
+ * [Init](#usage-init)
+ * [Start](#usage-start)
+ * [List](#usage-list)
+ * [Show](#usage-show)
+* [Interactions](#interactions)
+ * [Readline support](#interactions-readline-support)
+* [Guardfile DSL](#guardfile-dsl)
+ * [guard](#guardfile-dsl-guard)
+ * [watch](#guardfile-dsl-watch)
+ * [group](#guardfile-dsl-group)1
+ * [notification](#guardfile-dsl-notification)
+ * [interactor](#guardfile-dsl-interactor)
+ * [callback](#guardfile-dsl-callback)
+ * [ignore_paths](#guardfile-dsl-ignore-paths)
+ * [Example](#guardfile-dsl-example)
+* [Shared configurations](#shared-configuration)
+* [Advanced Linux system configuration](#advanced-linux-system-configuration)
+* [Create a Guard](#create-a-guard)
+* [Programmatic use of Guard](#programmatic-use-of-guard)
+* [File an issues](#file-an-issues)
+* [Development](#development)
+
+<a name="features" />
Features
--------
@@ -18,12 +55,14 @@ Features
* Support for visual system notifications.
* Tested against Ruby 1.8.7, 1.9.2, 1.9.3, REE and the latest versions of JRuby & Rubinius.
+<a name="screencast" />
Screencast
----------
Ryan Bates made an excellent [RailsCast about Guard](http://railscasts.com/episodes/264-guard) and you should definitely
watch it for a nice introduction to Guard.
+<a name="installation" />
Installation
------------
@@ -61,6 +100,7 @@ end
**It's important that you always run Guard through Bundler to avoid errors.** If you're getting sick of typing `bundle exec` all
the time, try the [Rubygems Bundler](https://github.com/mpapis/rubygems-bundler).
+<a name="installation-system-notifications" />
### System notifications
You can configure Guard to make use of the following system notification libraries, but it's strongly recommended
@@ -168,6 +208,7 @@ group :development do
end
```
+<a name="add-more-guards" />
Add more Guards
---------------
@@ -186,11 +227,13 @@ end
See the init section of the Guard usage below to see how to install the supplied Guard template that you can install and
to suit your needs.
+<a name="usage" />
Usage
-----
Guard is run from the command line. Please open your terminal and go to your project work directory.
+<a name="usage-help" />
### Help
You can always get help on the available tasks with the `help` task:
@@ -206,6 +249,7 @@ For example, to get help for the `start` task, simply run:
$ guard help start
```
+<a name="usage-init" />
### Init
You can generate a Guardfile and have all installed guards be automatically added into
@@ -243,6 +287,7 @@ $ guard init --bare
$ guard init -b # shortcut
```
+<a name="usage-start" />
### Start
Just launch Guard inside your Ruby or Rails project with:
@@ -348,6 +393,7 @@ $ guard start -B
$ guard start --no-bundler-warning
```
+<a name="usage-list" />
### List
You can list the available Guards with the `list` task:
@@ -368,6 +414,7 @@ See also https://github.com/guard/guard/wiki/List-of-available-Guards
* denotes ones already in your Guardfile
```
+<a name="usage-show" />
### Show
You can show the structure of the groups and their Guards with the `show` task:
@@ -388,6 +435,7 @@ Group frontend:
This shows the internal structure of the evaluated `Guardfile` or `.Guardfile`, with the `.guard.rb` file. You can
read more about these files in the shared configuration section below.
+<a name="interactions" />
Interactions
------------
@@ -425,6 +473,7 @@ This will reload only the Ronn Guard. You can also reload all Guards within a gr
> backend reload
```
+<a name="interactions-readline-support" />
### Readline support
With Readline enabled, you'll see a command prompt `>` when Guard is ready to accept a command. The command line
@@ -442,12 +491,14 @@ end
Guard will automatically enable Readline support if your environment supports it, but you can disable Readline with the
`interactor` DSL method or turn off completely with the `--no-interactions` option.
+<a name="guardfile-dsl" />
Guardfile DSL
-------------
The Guardfile DSL is evaluated as plain Ruby, so you can use normal Ruby code in your `Guardfile`.
Guard itself provides the following DSL methods that can be used for configuration:
+<a name="guardfile-dsl-guard" />
### guard
The `guard` method allows you to add a Guard to your toolchain and configure it by passing the
@@ -464,6 +515,7 @@ guard :coffeescript, :input => 'coffeescripts', :output => 'javascripts'
guard :coffeescript, :input => 'specs', :output => 'specs'
```
+<a name="guardfile-dsl-watch" />
### watch
The `watch` method allows you to define which files are watched by a Guard:
@@ -509,6 +561,7 @@ guard :shell do
end
```
+<a name="guardfile-dsl-group" />
### group
The `group` method allows you to group several Guards together. This comes in handy especially when you
@@ -536,6 +589,7 @@ $ guard -g specs
Guards that don't belong to a group are considered global and are always run.
+<a name="guardfile-dsl-notification" />
### notification
If you don't specify any notification configuration in your `Guardfile`, Guard goes through the list of available
@@ -572,6 +626,7 @@ or using the cli switch `-n`:
notification :off
```
+<a name="guardfile-dsl-interactor" />
### interactor
You can disable the interactor auto detection and for a specific implementation:
@@ -592,6 +647,7 @@ If you do not need the keyboard interactions with Guard at all, you can turn the
interactor :off
```
+<a name="guardfile-dsl-callback" />
### callback
The `callback` method allows you to execute arbitrary code before or after any of the `start`, `stop`, `reload`,
@@ -608,6 +664,7 @@ end
Please see the [hooks and callbacks](https://github.com/guard/guard/wiki/Hooks-and-callbacks) page in the Guard wiki for
more details.
+<a name="guardfile-dsl-ignore-paths" />
### ignore_paths
The `ignore_paths` method allows you to ignore top level directories altogether. This comes is handy when you have large
@@ -618,6 +675,7 @@ Currently it is only possible to ignore the immediate descendants of the watched
ignore_paths 'public'
```
+<a name="guardfile-dsl-example" />
### Example
```ruby
@@ -651,6 +709,7 @@ group :frontend do
end
```
+<a name="shared-configurations" />
Shared configurations
---------------------
@@ -668,6 +727,7 @@ guard :shell do
end
```
+<a name="advanced-linux-system-configuration" />
Advanced Linux system configuration
-----------------------------------
@@ -696,6 +756,7 @@ sudo sysctl -p
You may also need to pay attention to the values of `max_queued_events` and `max_user_instances`.
+<a name="create-a-guard" />
Create a Guard
--------------
@@ -807,6 +868,7 @@ end
[@avdi](https://github.com/avdi) has a very cool inline Guard example in his blog post
[A Guardfile for Redis](http://avdi.org/devblog/2011/06/15/a-guardfile-for-redis).
+<a name="programmatic-use-of-guard" />
Programmatic use of Guard
-------------------------
@@ -846,21 +908,28 @@ EOF
Guard.start(:guardfile_contents => guardfile)
```
-Issues
-------
+<a name="file-an-issues" />
+File an issue
+-------------
-You can report issues and feature requests to [GitHub Issues](https://github.com/guard/guard/issues). Try to figure out
-where the issue belongs to: Is it an issue with Guard itself or with a Guard implementation you're using? Please don't
-ask question in the issue tracker, instead join us in our [Google group](http://groups.google.com/group/guard-dev) or on
-`#guard` (irc.freenode.net).
+You can report bugs and feature requests to [GitHub Issues](https://github.com/guard/guard/issues).
+
+**Please don't ask question in the issue tracker**, instead ask them in our
+[Google group](http://groups.google.com/group/guard-dev) or on `#guard` (irc.freenode.net).
+
+Try to figure out where the issue belongs to: Is it an issue with Guard itself or with a Guard implementation you're
+using?
-When you file an issue, please try to follow to these simple rules if applicable:
+When you file a bug, please try to follow to these simple rules if applicable:
* Make sure you run Guard with `bundle exec` first.
* Add verbose information to the issue by running Guard with the `--verbose` option.
* Add your `Guardfile` and `Gemfile` to the issue.
* Make sure that the issue is reproducible with your description.
+**It's most likely that your bug gets resolved faster if you provide as much information as possible!***
+
+<a name="development" />
Development [![Dependency Status](https://gemnasium.com/guard/guard.png?branch=master)](https://gemnasium.com/guard/guard)
-----------
@@ -880,19 +949,16 @@ Pull requests are very welcome! Please try to follow these simple rules if appli
For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
`#guard` (irc.freenode.net).
-Core Team
----------
+### Author
+
+[Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](http://twitter.com/thibaudgg))
+
+### Core Team
* [Michael Kessler](https://github.com/netzpirat) ([@netzpirat](http://twitter.com/netzpirat)), sponsored by [mksoft.ch](https://mksoft.ch)
* [Rémy Coutable](https://github.com/rymai) ([@rymai](http://twitter.com/rymai))
* [Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](http://twitter.com/thibaudgg))
-Author
-------
-
-[Thibaud Guillaume-Gentil](https://github.com/thibaudgg) ([@thibaudgg](http://twitter.com/thibaudgg))
-
-Contributors
-------------
+### Contributors
[https://github.com/guard/guard/contributors](https://github.com/guard/guard/contributors)

2 comments on commit 77eb27c

@Maher4Ever
Guard member

Did you consider moving the technical information to the Wiki of Guard and write a simple introduction in the README?

@netzpirat

I thought about it, but haven't taken any actions yet. I think the more technical stuff like advanced Linux configuration, programatic use of Guard and create a Guard section are good wiki candidates. For the rest I think it may be better to leave it in the README, because many users are lazy and will open an issue for asking instead of browsing the wiki. Less clicks are better for lazy users :P

Please sign in to comment.