Skip to content

Commit

Permalink
Move advanced README stuff to the wiki.
Browse files Browse the repository at this point in the history
  • Loading branch information
@netzpirat
netzpirat committed May 31, 2012
1 parent 572b22a commit 7ddc814
Showing 1 changed file with 0 additions and 171 deletions.
171 changes: 0 additions & 171 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -694,177 +694,6 @@ guard :shell do
end
```

Advanced Linux system configuration
-----------------------------------

It's not uncommon to encounter a system limit on the number of files you can monitor.
For example, Ubuntu Lucid's (64bit) inotify limit is set to 8192.

You can get your current inotify file watch limit by executing:

```bash
$ cat /proc/sys/fs/inotify/max_user_watches
```

And set a new limit temporary with:

```bash
sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl -p
```

If you like to make your limit permanent, use:

```bash
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```

You may also need to pay attention to the values of `max_queued_events` and `max_user_instances`.

Create a Guard
--------------

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.

```bash
$ mkdir guard-yoyo
$ cd guard-yoyo
$ bundle gem guard-yoyo
```

Now extend the project structure to have an initial Guard:

```bash
.travis.yml # bonus point!
CHANGELOG.md # bonus point!
Gemfile
guard-yoyo.gemspec
Guardfile
lib/
guard/
yoyo/
templates/
Guardfile # needed for `guard init <guard-name>`
version.rb
yoyo.rb
test/ # or spec/
README.md
```

Your Guard main class `Guard::Yoyo` in `lib/guard/guard-yoyo.rb` must inherit from
[Guard::Guard](http://rubydoc.info/github/guard/guard/master/Guard/Guard) and should implement at least the
`#run_on_changes` task method. `#run_on_additions`, `#run_on_modifications` and `#run_on_removals` task methods
could be use instead of `#run_on_changes` task method for more control about how changes are handled.

Here is an example scaffold for `lib/guard/yoyo.rb`:

```ruby
require 'guard'
require 'guard/guard'

module Guard
class Yoyo < Guard

# Initialize a Guard.
# @param [Array<Guard::Watcher>] watchers the Guard file watchers
# @param [Hash] options the custom Guard options
def initialize(watchers = [], options = {})
super
end

# Call once when Guard starts. Please override initialize method to init stuff.
# @raise [:task_has_failed] when start has failed
def start
end

# Called when `stop|quit|exit|s|q|e + enter` is pressed (when Guard quits).
# @raise [:task_has_failed] when stop has failed
def stop
end

# Called when `reload|r|z + enter` is pressed.
# This method should be mainly used for "reload" (really!) actions like reloading passenger/spork/bundler/...
# @raise [:task_has_failed] when reload has failed
def reload
end

# Called when just `enter` is pressed
# This method should be principally used for long action like running all specs/tests/...
# @raise [:task_has_failed] when run_all has failed
def run_all
end

# Default behaviour on file(s) changes that the Guard watches.
# @param [Array<String>] paths the changes files or paths
# @raise [:task_has_failed] when run_on_change has failed
def run_on_changes(paths)
end
end
end
```

Please take a look at the source code of some of the [existing Guards](https://github.com/guard)
for more concrete example and inspiration.

Alternatively, a new Guard can be added inline to a `Guardfile` with this basic structure:

```ruby
require 'guard/guard'

module ::Guard
class InlineGuard < ::Guard::Guard
def run_all
end

def run_on_changes(paths)
end
end
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).

Programmatic use of Guard
-------------------------

The Guardfile DSL can also be used in a programmatic fashion by calling
[Guard::Dsl.evaluate_guardfile](http://rubydoc.info/github/guard/guard/master/Guard/Dsl#evaluate_guardfile-class_method).

Available options are as follow:

* `:guardfile` - The path to a valid `Guardfile`.
* `:guardfile_contents` - A string representing the content of a valid `Guardfile`.

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.

Evaluate a `Guardfile`:

```ruby
require 'guard'

Guard.setup
Guard.start(:guardfile => '/path/to/Guardfile')
```

Evaluate a string as `Guardfile`:

```ruby
require 'guard'

Guard.setup

guardfile = <<-EOF
guard 'rspec' do
watch(%r{^spec/.+_spec\.rb$})
end
EOF

Guard.start(:guardfile_contents => guardfile)
```

File an issue
-------------

Expand Down

0 comments on commit 7ddc814

Please sign in to comment.