# rerun: restart a process when its files change

> rerun is a small Ruby gem that launches your program, watches the filesystem, and restarts the program when a relevant file changes, with no config file and no language lock-in. It suits a developer working on a long-running app or a test suite, and it deliberately borrows the process semantics you already had from the command line.

**alexch/rerun** — Restarts an app when the filesystem changes. Uses growl and FSEventStream if on OS X.

- Repository: https://github.com/alexch/rerun
- Stars: 989 · Forks: 87
- Language: Ruby
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/alexch-rerun

## The whole mechanism is exec and a signal

Rerun launches your program, then watches the filesystem, and if a relevant file changes it restarts your program. That is the entire description, and the reason it works on any command is that there is nothing framework specific in it.

The README states the design advantage plainly. Since it uses exec and the standard Unix SIGINT and SIGKILL signals, you are sure the restarted app is really acting just like it was when you ran it from the command line the first time. The process is replaced rather than spawned as a child of a supervisor, and the signals are the ones you would have used yourself.

That is a meaningful difference from the tools it positions itself against. It describes itself as a no-frills command-line alternative to Guard, Shotgun and Autotest, with two differences: it does not require config files, and it works on any command, not just Ruby programs. A watcher that reloads a Rails application in place knows about Rails. Rerun does not, and pays for that by restarting the process.

It works for both long-running processes such as apps and short-running ones such as tests, which is the same code path with a different expectation about how long the process lives.

The project is a small Ruby gem with a spec/ directory, a Rakefile, a Vagrantfile, and a .travis.yml. The licence is reported as one GitHub cannot classify, and the last push to the master branch was on 2026-04-15 with no GitHub releases.

## Installing it, and the adapter gems that decide how it watches

The install is a gem install, and the README adds a note that sudo may be required on older systems but to try without it first.

```
gem install rerun
```

If you use RVM you might want to put it in your global gemset so it is available to all your apps, and the README gives the command:

```
rvm @global do gem install rerun
```

Then comes the part that catches people out. The Listen gem, which rerun uses as of version 0.7.0, looks for platform-dependent adapter gems and complains if they are not available. The README is explicit that Rubygems does not understand optional dependencies very well, so you may have to install extra gems and put them in your Gemfile, and it points at the Listen adapters documentation.

The adapters are per platform: rb-fsevent on Mac OS X, wdm on Windows, and rb-kqueue on BSD.

That complaint from Rubygems is a packaging problem rather than a rerun problem, and it is why the README recommends the Gemfile route for anyone inside an existing application. The Gemfile form is:

``` ruby
group :development, :test do
  gem "rerun"
end
```

and the same block with a git source is how you use the pre-release branch, which may have bugfixes or features you want:

``` ruby
group :development, :test do
  gem "rerun", git: "https://github.com/alexch/rerun.git"
end
```

The README also says to install with bundle install or bundle update and run with bundle exec rerun, to guarantee you are using the version specified in the Gemfile and not a different one in a system-wide gemset.

## The command line, and the cases the README works through

The usage is a single form:

```
rerun [options] [--] cmd
```

And the examples build up from there. For a Sinatra app whose main file is app.rb, `rerun ruby app.rb` works, and because the first part of the command is a .rb filename, ruby is optional, so `rerun app.rb` does the same thing. For Rails, which does not automatically notice all config file changes, you can force a restart when a config file changes with `rerun --dir config rails s`.

For a Rack app run with Thin, on port 4000 in debug mode, watching only the app and web subdirectories:

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

The -- is there to separate rerun options from the command's own options, and the README notes you can use a quoted string instead, such as `rerun --dir app "thin start --debug --port=4000 -R config.ru"`. Rackup is covered too, with `rerun -- rackup --port 4000 config.ru`.

The autotest style is a flag rather than a separate mode, `rerun -x rake` and `rerun -cx rspec`, and the Rails Spork case is handled by putting rerun in a Rakefile task:

```
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
```

That task is the most instructive example in the README, because it shows the pattern option used to watch a specific list of files rather than an extension list, and because it shows rerun invoked from inside another process. The Erector case, `rerun -x erector --to-html my_site.rb`, regenerates HTML after every change, and the Heroku Cedar section notes that rerun is now compatible with foreman, so `rerun foreman start` runs all your Procfile processes locally and restarts them when necessary.

## The options, and what a pattern actually matches

Options can be given on the command line or inside a .rerun config file, and there are several that change what gets watched rather than how the restart works.

The --dir option takes the directory or directories to watch, defaulting to the current directory, and you separate multiple paths with a comma or use several -d options. The --pattern option is a glob to match inside the directory, using the Ruby Dir glob style.

By default it watches files ending in rb, js, coffee, css, scss, sass, erb, html, haml, ru, yml, slim, md, feature, c and h. On top of the pattern it ignores dotfiles, .tmp files, and other files and directories such as .git and log, and you can see the actual list with `rerun --help`. The --ignore option takes a file glob to ignore and can be set many times, and to ignore a directory you must append /*, so `--ignore 'coverage/*'`.

The dotfile rule has an escape hatch. By default, on top of --pattern and --ignore, it ignores any changes to files and directories starting with a dot, and --no-ignore-dotfiles allows you to monitor a relevant file like .env, with the warning that you may then have to explicitly ignore more dotfiles and dotdirs.

That is worth understanding, because it is a common source of confusion. Someone watches for a change to .env and nothing happens, and the answer is that .env was never watched in the first place.

The restart semantics are configurable too. The --signal or -s option takes the signals used to terminate the previous process instead of the default TERM,INT,KILL, and you can pass a comma-delimited list to try one signal, wait up to five seconds for the process to die, then try the next. The --wait or -w option sets how long to wait after asking the process to terminate before aborting or trying the next signal in the series, defaulting to two seconds. And --restart or -r expects the process to restart itself using HUP by default, so -r -s INT sends an INT and then resumes watching.

## Windows support, and the caveats that come with it

The README has a section headed UPDATE that announces that rerun does now work on Windows, followed by four caveats, and the honesty here is what makes the section useful.

It is not well-tested. You need to press Enter after keypress input. You may need to install the wdm gem manually with `gem install wdm`. And you may see a persistent INFO error message, which you can remove with --no-notify:

```
INFO: Could not find files for the given pattern(s)
```

That last one is the kind of detail that only appears when someone has actually run the tool on that platform for a while. The message is not a failure, it is the watcher reporting that it found no files matching, and on Windows it apparently persists even when it should not, so the tool grew a flag to silence it rather than leaving every user to wonder.

The keyboard caveat is a consequence of how the process is attached. Since rerun uses exec, the terminal and the child process share a console, and a shell that reads a line rather than a single keypress will consume the keystroke and wait for Enter. That is a real difference from a native Windows application and it is not something the watcher can paper over.

The project is old enough that the Windows work reads as an addition to a Unix-first design, and the repository shows the same. There is a Vagrantfile, so a development environment was meant to be reproducible, and the top level carries a .travis.yml for continuous integration along with a .rspec file, a gemspec, a geminstaller.yml, and an issues.json and pulls.json pair.

## Conclusion

Adopt rerun if you want a file watcher that does not impose a project layout or a config file, because it works on any command, not just Ruby programs, and it uses exec plus standard Unix signals so the restarted process behaves the way it did when you launched it yourself. Do not adopt it if you need a watcher that understands your framework, since rerun deliberately does not, and it restarts the whole process rather than reloading parts of it. Before you install, add the platform adapter gem for your system, rb-fsevent on macOS, wdm on Windows or rb-kqueue on BSD, and note the Windows caveats in the README, including the wdm gem and the persistent INFO message that --no-notify suppresses.

## FAQ

### What does the rerun gem do?

It launches your program, watches the filesystem, and restarts the program when a relevant file changes. It works for both long-running processes such as apps and short-running ones such as tests, and it needs no config file, working on any command rather than only Ruby programs.

### How do I install rerun and the platform adapter gems?

Install with `gem install rerun`, and add the Listen adapter for your platform: rb-fsevent on Mac OS X, wdm on Windows, rb-kqueue on BSD. The README notes that Rubygems does not handle optional dependencies well, so inside an existing application it recommends adding `gem "rerun"` to a Gemfile group and running with bundle exec rerun.

### Which files does rerun watch by default?

By default it watches files ending in rb, js, coffee, css, scss, sass, erb, html, haml, ru, yml, slim, md, feature, c and h, and ignores dotfiles, .tmp files and directories such as .git and log. The --pattern option changes the glob, --ignore excludes specific globs, and --no-ignore-dotfiles lets you watch something like .env.

### What are the caveats when using rerun on Windows?

The README lists them: it is not well-tested, you need to press Enter after keypress input, you may need to install the wdm gem manually, and you may see a persistent INFO message about files for the given patterns, which you can remove with --no-notify.

## Sources

- [alexch/rerun on GitHub](https://github.com/alexch/rerun)
- [Issues](https://github.com/alexch/rerun/issues)
- [README](https://github.com/alexch/rerun/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alexch-rerun