Rerun ↑

A fork of the original rerun: github.com/alexch/rerun

This fork only releases the latest commit to rubygems, which includes the --force-polling-flag and therefore work on WSL.

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

Rerun does not work on Windows. Sorry, but you can't do much relaunching without “fork”.

Installation: ↑

    gem install rerun

(“sudo” may be required on older systems, but try it without sudo first.)

If you are using RVM you might want to put this in your global gemset so it's available to all your apps. (There really should be a better way to distinguish gems-as-libraries from gems-as-tools.)

    rvm @global do gem install rerun

The Listen gem looks for certain platform-dependent gems, and will complain if they're not available. Unfortunately, Rubygems doesn't understand optional dependencies very well, so you may have to install extra gems (and/or put them in your Gemfile) to make Rerun work more smoothly on your system. (Learn more at github.com/guard/listen#listen-adapters.) For example, on Mac OS X, use

    gem install rb-fsevent

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? Try

    rerun -x rake

or

    rerun -cx rspec

And if you're using Spork with Rails, you need to restart your spork server 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 for a similar solution.)

How about regenerating your HTML files after every change to your Erector 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: ↑

--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 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. 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 (instead of the default SIGTERM) to terminate the previous process. This may be useful for forcing the respective process to terminate as quickly as possible. (--signal KILL is the equivalent of kill -9)

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

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

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

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

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

--no-notify don't use growl (or osx) notifications

--name set the app name (for display)

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

Also --version and --help, naturally.

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 both, Rerun will pick one, or you can choose between them using --notify growl or --notify osx respectively.

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

Download growlnotify here now that Growl has moved to the App Store.

Install 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-The-Fly Commands ↑

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

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:

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 4 to 6 seconds to restart.

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 ↑

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

To Do: ↑

Must have for v1.0 ↑

Nice to have ↑

Wacky Ideas ↑

Other projects that do similar things ↑

Why would I use this instead of Shotgun? ↑

Shotgun does a “fork” after the web framework has loaded but before your application is loaded. It then loads your app, processes a single request in the child process, then exits the child process.

Rerun launches the whole app, then when it's time to restart, uses “kill” to shut it down and starts the whole thing up again from scratch.

So rerun takes somewhat longer than Shotgun to restart the app, but does it much less frequently. And once it's running it behaves more normally and consistently with your production app.

Also, Shotgun reloads the app on every request, even if it doesn't need to. This is fine if you're loading a single file, but if your web pages all load other files (CSS, JS, media) then that adds up quickly. (I can only assume that the developers of shotgun are using caching or a front web server so this isn't a pain point for them.)

And hey, does Shotgun reload your Worker processes if you're using Foreman and a Procfile? I'm pretty sure it doesn't.

YMMV!

Why would I use this instead of Rack::Reloader? ↑

Rack::Reloader is certifiably beautiful code, and is a very elegant use of Rack's middleware architecture. But because it relies on the LOADED_FEATURES variable, it only reloads .rb files that were 'require'd, not 'load'ed. That leaves out (non-Erector) template files, and also, at least the way I was doing it, sub-actions (see this thread).

Rack::Reloader also doesn't reload configuration changes or redo other things that happen during app startup. Rerun takes the attitude that if you want to restart an app, you should just restart the whole app. You know?

Why would I use this instead of Guard? ↑

Guard is very powerful but requires some up-front configuration. Rerun is meant as a no-frills command-line alternative requiring no knowledge of Ruby nor config file syntax.

Why did you write this? ↑

I've been using Sinatra and loving it. In order to simplify their system, the Rat Pack removed auto-reloading from Sinatra proper. I approve of this: a web application framework should be focused on serving requests, not on munging Ruby ObjectSpace for dev-time convenience. But I still wanted automatic reloading during development. Shotgun wasn't working for me (see above) so I spliced Rerun together out of code from Rspactor, FileSystemWatcher, and Shotgun – with a heavy amount of refactoring and rewriting. In late 2012 I migrated the backend to the Listen gem, which was extracted from Guard, so it should be more reliable and performant on multiple platforms.

Credits ↑

Rerun: Alex Chaffee, alex@stinky.com, github.com/alexch/

Based upon and/or inspired by:

Patches by: ↑

Version History ↑

* * --force-polling option (thanks ajduncan)

License ↑

Open Source MIT License. See “LICENSE” file.