# rerun(1)

## NAME

rerun - run programs and restarts them on filesystem changes

## DESCRIPTION

Rerun launches your program, then watches the filesystem. If a relevant file
changes, then it restarts your program.

Rerun works for both long-running processes (e.g. apps) and short-running ones
(e.g. tests). It's basically a no-frills command-line alternative to Guard,
Shotgun, Autotest, etc. that doesn't require config files and works on any
command, not just Ruby programs.

Rerun's advantage is its simple design. Since it uses `exec` and the standard
Unix `SIGINT` and `SIGKILL` signals, you're sure the restarted app is really
acting just like it was when you ran it from the command line the first time.

By default it watches files ending in: `rb,js,coffee,css,scss,sass,erb,html,haml,ru,yml,slim,md,feature,c,h`.
Use the `--pattern` option if you want to change this.

As of version 0.7.0, we use the Listen gem, which tries to use your OS's
built-in facilities for monitoring the filesystem, so CPU use is very light.

**UPDATE**: Now Rerun *does* work on Windows. Caveats:
  * not well-tested
  * after running, it may continue to slurp up some of your console input, so run it in a separate window, and/or use `--background` to disable on-the-fly commands, and/or press `q` to quit instead of CTRL-C
  * you may need to install the `wdm` gem manually: `gem install wdm`
  * You may see this persistent `INFO` error message; to remove it, use`--no-notify`:
    * `INFO: Could not find files for the given pattern(s)`

## USAGE

        rerun [options] [--] cmd

For example, if you're running a Sinatra app whose main file is `app.rb`:

        rerun ruby app.rb

If the first part of the command is a `.rb` filename, then `ruby` is
optional, so the above can also be accomplished like this:

        rerun app.rb

Rails doesn't automatically notice all config file changes, so you can force it
to restart when you change a config file like this:

        rerun --dir config rails s

Or if you're using Thin to run a Rack app that's configured in config.ru
but you want it on port 4000 and in debug mode, and only want to watch
the `app` and `web` subdirectories:

        rerun --dir app,web -- thin start --debug --port=4000 -R config.ru

The `--` is to separate rerun options from cmd options. You can also
use a quoted string for the command, e.g.

        rerun --dir app "thin start --debug --port=4000 -R config.ru"

Rackup can also be used to launch a Rack server, so let's try that:

        rerun -- rackup --port 4000 config.ru

Want to mimic [autotest](https://github.com/grosser/autotest)? Try

        rerun -x rake

or

        rerun -cx rspec

And if you're using [Spork](https://github.com/sporkrb/spork) with Rails, you
need to [restart your spork server](https://github.com/sporkrb/spork/issues/201)
whenever certain Rails environment files change, so why not put this in your
Rakefile...

    desc "run spork (via rerun)"
    task :spork do
      sh "rerun --pattern '{Gemfile,Gemfile.lock,spec/spec_helper.rb,.rspec,spec/factories/**,config/environment.rb,config/environments/test.rb,config/initializers/*.rb,lib/**/*.rb}' -- spork"
    end

and start using `rake spork` to launch your spork server?

(If you're using Guard instead of Rerun, check out
[guard-spork](https://github.com/guard/guard-spork)
for a similar solution.)

How about regenerating your HTML files after every change to your
[Erector](http://erector.rubyforge.org) widgets?

        rerun -x erector --to-html my_site.rb

Use Heroku Cedar? `rerun` is now compatible with `foreman`. Run all your
Procfile processes locally and restart them all when necessary.

        rerun foreman start

## OPTIONS

These options can be specified on the command line and/or inside a `.rerun` config file (see below).

`--dir` directory (or directories) to watch (default = "."). Separate multiple paths with ',' and/or use multiple `-d` options.

`--pattern` glob to match inside directory. This uses the Ruby Dir glob style -- see <http://www.ruby-doc.org/core/classes/Dir.html#M002322> for details.
By default it watches files ending in: `rb,js,coffee,css,scss,sass,erb,html,haml,ru,yml,slim,md,feature,c,h`.
On top of this, it also ignores dotfiles, `.tmp` files, and some other files and directories (like `.git` and `log`).
Run `rerun --help` to see the actual list.

`--ignore pattern` file glob to ignore (can be set many times). To ignore a directory, you must append `'/*'` e.g.
  `--ignore 'coverage/*'`.

  *On top of --pattern and --ignore, we ignore any changes to files and dirs starting with a dot.*

`--signal` (or `-s`) use specified signal(s) (instead of the default `TERM,INT,KILL`) to terminate the previous process. You can use a comma-delimited list if you want to try a signal, wait up to 5 seconds for the process to die, then try again with a different signal, and so on. 
This may be useful for forcing the respective process to terminate as quickly as possible.
(`--signal KILL` is the equivalent of `kill -9`)

`--wait sec` (or `-w`)           after asking the process to terminate, wait this long (in seconds) before either aborting, or trying the next signal in series. Default: 2 sec

`--restart` (or `-r`) expect process to restart itself, using signal HUP by default
(e.g. `-r -s INT` will send a INT and then resume watching for changes)

`--exit` (or -x) expect the program to exit. With this option, rerun checks the return value; without it, rerun checks that the launched process is still running.

`--clear` (or -c) clear the screen before each run

`--background` (or -b) disable on-the-fly commands, allowing the process to be backgrounded

`--notify NOTIFIER` use `growl` or `osx` or `notify-send` for notifications (see below)

`--no-notify` disable notifications

`--name` set the app name (for display)

`--force-polling` use polling instead of a native filesystem scan (useful for Vagrant)

`--quiet` silences most messages

`--verbose` enables even more messages (unless you also specified `--quiet`, which overrides `--verbose`)

Also `--version` and `--help`, naturally.

## CONFIG FILE

If the current directory contains a file named `.rerun`, it will be parsed with the same rules as command-line arguments. Newlines are the same as any other whitespace, so you can stack options vertically, like this:

```
--quiet
--pattern **/*.{rb,js,scss,sass,html,md}
```

Options specified on the command line will override those in the config file. You can negate boolean options with `--no-`, so for example, with the above config file, to re-enable logging, you could say:

```sh
rerun --no-quiet rackup
```

If you're not sure what options are being overwritten, use `--verbose` and rerun will show you the final result of the parsing.

## NOTIFICATIONS

If you have `growlnotify` available on the `PATH`, it sends notifications to
growl in addition to the console.

If you have `terminal-notifier`, it sends notifications to
the OS X notification center in addition to the console.

If you have `notify-send`, it sends notifications to Freedesktop-compatible
desktops in addition to the console.

If you have more than one available notification program, Rerun will pick one, or you can choose between them using `--notify growl`, `--notify osx`, `--notify notify-send`, etc.

If you have a notifier installed but don't want rerun to use it,
set the `--no-notify` option.

Download [growlnotify here](http://growl.info/downloads.php#generaldownloads)
now that Growl has moved to the App Store.

Install [terminal-notifier](https://github.com/julienXX/terminal-notifier) using `gem install terminal-notifier`. (You may have to put it in your system gemset and/or use `sudo` too.) Using Homebrew to install terminal-notifier is not recommended.

On Debian/Ubuntu, `notify-send` is availble in the `libnotify-bin` package. On other GNU/Linux systems, it might be in a package with a different name.

## ON-THE-FLY COMMANDS

While the app is (re)running, you can make things happen by pressing keys:

* **r** -- restart (as if a file had changed)
* **f** -- force restart (stop and start)
* **c** -- clear the screen
* **x** or **q** -- exit (just like control-C)
* **p** -- pause/unpause filesystem watching

If you're backgrounding or using Pry or a debugger, you might not want these
keys to be trapped, so use the `--background` option.

## SIGNALS

The current algorithm for killing the process is:

* send [SIGTERM](http://en.wikipedia.org/wiki/SIGTERM) (or the value of the `--signal` option)
* if that doesn't work after 2 seconds, send SIGINT (aka control-C)
* if that doesn't work after 2 more seconds, send SIGKILL (aka kill -9)

This seems like the most gentle and unixy way of doing things, but it does
mean that if your program ignores SIGTERM, it takes an extra 2 to 4 seconds to
restart.

If you want to use your own series of signals, use the `--signal` option. If you want to change the delay before attempting the next signal, use the `--wait` option.

## Vagrant and VirtualBox

If running inside a shared directory using Vagrant and VirtualBox, you must pass the `--force-polling` option. You may also have to pass some extra `--ignore` options too; otherwise each scan can take 10 or more seconds on directories with a large number of files or subdirectories underneath it.

## TROUBLESHOOTING

### Vagrant

Rerun will not pick up changes made to shared folders. This means that the common
method of using Vagrant for an execution environment and using the `/vagrant`
shared folder for source code will not work.

Instead, use [shotgun](https://rubygems.org/gems/shotgun).

### zsh

If you are using `zsh` as your shell, and you are specifying your `--pattern` as `**/*.rb`, you may face this error
```
Errno::EACCES: Permission denied - <filename>
```
This is because `**/*.rb` gets expanded into the command by `zsh` instead of passing it through to rerun. The solution is to simply quote ('' or "") the pattern.
i.e
```
rerun -p **/*.rb rake test
```
becomes
```
rerun -p "**/*.rb" rake test
```
