Skip to content

Commit

Permalink
Add a TOC, polish the file an issue section.
Browse files Browse the repository at this point in the history
  • Loading branch information
@netzpirat
netzpirat committed Mar 12, 2012
1 parent 69b8a52 commit 77eb27c
Showing 1 changed file with 84 additions and 18 deletions.
102 changes: 84 additions & 18 deletions README.md
View file
Expand Up @@ -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
--------

Expand All @@ -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
------------

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -168,6 +208,7 @@ group :development do
end
```

<a name="add-more-guards" />
Add more Guards
---------------

Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -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
------------

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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`,
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -651,6 +709,7 @@ group :frontend do
end
```

<a name="shared-configurations" />
Shared configurations
---------------------

Expand All @@ -668,6 +727,7 @@ guard :shell do
end
```

<a name="advanced-linux-system-configuration" />
Advanced Linux system configuration
-----------------------------------

Expand Down Expand Up @@ -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
--------------

Expand Down Expand Up @@ -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
-------------------------

Expand Down Expand Up @@ -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)
-----------

Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@netzpirat
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.