'\" t
.\"     Title: rerun
.\"    Author: [see the "AUTHORS" section]
.\" Generator: Asciidoctor 1.5.4
.\"      Date: 2016-05-09
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "RERUN" "1" "2016-05-09" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.LINKSTYLE blue R < >
.SH "NAME"
rerun \- run programs and restarts them on filesystem changes
.SH "DESCRIPTION"
.sp
Rerun launches your program, then watches the filesystem. If a relevant file
changes, then it restarts your program.
.sp
Rerun works for both long\-running processes (e.g. apps) and short\-running ones
(e.g. tests). It\(cqs basically a no\-frills command\-line alternative to Guard,
Shotgun, Autotest, etc. that doesn\(cqt require config files and works on any
command, not just Ruby programs.
.sp
Rerun\(cqs advantage is its simple design. Since it uses \f[CR]exec\fP and the standard
Unix \f[CR]SIGINT\fP and \f[CR]SIGKILL\fP signals, you\(cqre sure the restarted app is really
acting just like it was when you ran it from the command line the first time.
.sp
By default it watches files ending in: \f[CR]rb,js,coffee,css,scss,sass,erb,html,haml,ru,yml,slim,md,feature\fP.
Use the \f[CR]\-\-pattern\fP option if you want to change this.
.sp
As of version 0.7.0, we use the Listen gem, which tries to use your OS\(cqs
built\-in facilities for monitoring the filesystem, so CPU use is very light.
.sp
Rerun does not work on Windows. Sorry, but you can\(cqt do much relaunching
without "fork".
.SH "USAGE"
.sp
.if n \{\
.RS 4
.\}
.nf
rerun [options] [\-\-] cmd
.fi
.if n \{\
.RE
.\}
.sp
For example, if you\(cqre running a Sinatra app whose main file is \f[CR]app.rb\fP:
.sp
.if n \{\
.RS 4
.\}
.nf
rerun ruby app.rb
.fi
.if n \{\
.RE
.\}
.sp
If the first part of the command is a \f[CR].rb\fP filename, then \f[CR]ruby\fP is
optional, so the above can also be accomplished like this:
.sp
.if n \{\
.RS 4
.\}
.nf
rerun app.rb
.fi
.if n \{\
.RE
.\}
.sp
Rails doesn\(cqt automatically notice all config file changes, so you can force it
to restart when you change a config file like this:
.sp
.if n \{\
.RS 4
.\}
.nf
rerun \-\-dir config rails s
.fi
.if n \{\
.RE
.\}
.sp
Or if you\(cqre using Thin to run a Rack app that\(cqs configured in config.ru
but you want it on port 4000 and in debug mode, and only want to watch
the \f[CR]app\fP and \f[CR]web\fP subdirectories:
.sp
.if n \{\
.RS 4
.\}
.nf
rerun \-\-dir app,web \-\- thin start \-\-debug \-\-port=4000 \-R config.ru
.fi
.if n \{\
.RE
.\}
.sp
The \f[CR]\-\-\fP is to separate rerun options from cmd options. You can also
use a quoted string for the command, e.g.
.sp
.if n \{\
.RS 4
.\}
.nf
rerun \-\-dir app "thin start \-\-debug \-\-port=4000 \-R config.ru"
.fi
.if n \{\
.RE
.\}
.sp
Rackup can also be used to launch a Rack server, so let\(cqs try that:
.sp
.if n \{\
.RS 4
.\}
.nf
rerun \-\- rackup \-\-port 4000 config.ru
.fi
.if n \{\
.RE
.\}
.sp
Want to mimic [autotest](\c
.URL "https://github.com/grosser/autotest)?" "" " "
Try
.sp
.if n \{\
.RS 4
.\}
.nf
rerun \-x rake
.fi
.if n \{\
.RE
.\}
.sp
or
.sp
.if n \{\
.RS 4
.\}
.nf
rerun \-cx rspec
.fi
.if n \{\
.RE
.\}
.sp
And if you\(cqre using [Spork](\c
.URL "https://github.com/sporkrb/spork" "" ")"
with Rails, you
need to [restart your spork server](\c
.URL "https://github.com/sporkrb/spork/issues/201" "" ")"
whenever certain Rails environment files change, so why not put this in your
Rakefile...
.sp
.if n \{\
.RS 4
.\}
.nf
desc "run spork (via rerun)"
task :spork do
  sh "rerun \-\-pattern \(aq{Gemfile,Gemfile.lock,spec/spec_helper.rb,.rspec,spec/factories/**,config/environment.rb,config/environments/test.rb,config/initializers/*.rb,lib/**/*.rb}\(aq \-\- spork"
end
.fi
.if n \{\
.RE
.\}
.sp
and start using \f[CR]rake spork\fP to launch your spork server?
.sp
(If you\(cqre using Guard instead of Rerun, check out
[guard\-spork](\c
.URL "https://github.com/guard/guard\-spork" "" ")"
for a similar solution.)
.sp
How about regenerating your HTML files after every change to your
[Erector](\c
.URL "http://erector.rubyforge.org" "" ")"
widgets?
.sp
.if n \{\
.RS 4
.\}
.nf
rerun \-x erector \-\-to\-html my_site.rb
.fi
.if n \{\
.RE
.\}
.sp
Use Heroku Cedar? \f[CR]rerun\fP is now compatible with \f[CR]foreman\fP. Run all your
Procfile processes locally and restart them all when necessary.
.sp
.if n \{\
.RS 4
.\}
.nf
rerun foreman start
.fi
.if n \{\
.RE
.\}
.SH "OPTIONS"
.sp
\f[CR]\-\-dir\fP directory (or directories) to watch (default = "."). Separate multiple paths with \(aq,\(aq and/or use multiple \f[CR]\-d\fP options.
.sp
\f[CR]\-\-pattern\fP glob to match inside directory. This uses the Ruby Dir glob style \(em; see \c
.URL "http://www.ruby\-doc.org/core/classes/Dir.html#M002322" "" " "
for details.
By default it watches files ending in: \f[CR]rb,js,coffee,css,scss,sass,erb,html,haml,ru,yml,slim,md,feature\fP.
On top of this, it also ignores dotfiles, \f[CR].tmp\fP files, and some other files and directories (like \f[CR].git\fP and \f[CR]log\fP).
Run \f[CR]rerun \-\-help\fP to see the actual list.
.sp
\f[CR]\-\-ignore pattern\fP file glob to ignore (can be set many times). To ignore a directory, you must append \(aq/\fB\(aq e.g.
  \f[CR]\-\-ignore \(aqcoverage/\fP\(aq\fP.
.sp
.if n \{\
.RS 4
.\}
.nf
*On top of \-\-pattern and \-\-ignore, we ignore any changes to files and dirs starting with a dot.*
.fi
.if n \{\
.RE
.\}
.sp
\f[CR]\-\-signal\fP (or \f[CR]\-s\fP) 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.
(\f[CR]\-\-signal KILL\fP is the equivalent of \f[CR]kill \-9\fP)
.sp
\f[CR]\-\-restart\fP (or \f[CR]\-r\fP) expect process to restart itself, using signal HUP by default
(e.g. \f[CR]\-r \-s INT\fP will send a INT and then resume watching for changes)
.sp
\f[CR]\-\-clear\fP (or \-c) clear the screen before each run
.sp
\f[CR]\-\-exit\fP (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.
.sp
\f[CR]\-\-background\fP (or \-b) disable on\-the\-fly commands, allowing the process to be backgrounded
.sp
\f[CR]\-\-notify NOTIFIER\fP use \f[CR]growl\fP or \f[CR]osx\fP for notifications (see below)
.sp
\f[CR]\-\-no\-notify\fP don\(cqt use growl (or osx) notifications
.sp
\f[CR]\-\-name\fP set the app name (for display)
.sp
Also \f[CR]\-\-version\fP and \f[CR]\-\-help\fP, naturally.
.SH "NOTIFICATIONS"
.sp
If you have \f[CR]growlnotify\fP available on the \f[CR]PATH\fP, it sends notifications to
growl in addition to the console.
If you have \f[CR]terminal\-notifier\fP, it sends notifications to
the OS X notification center in addition to the console.
.sp
If you have both, Rerun will pick one, or you can choose between them using \f[CR]\-\-notify growl\fP or \f[CR]\-\-notify osx\fP respectively.
.sp
If you have a notifier installed but don\(cqt want rerun to use it,
set the \f[CR]\-\-no\-notify\fP option.
.sp
Download [growlnotify here](\c
.URL "http://growl.info/downloads.php#generaldownloads" "" ")"
now that Growl has moved to the App Store.
.sp
Install [terminal\-notifier](\c
.URL "https://github.com/julienXX/terminal\-notifier" "" ")"
using \f[CR]gem install terminal\-notifier\fP. (You may have to put it in your system gemset and/or use \f[CR]sudo\fP too.) Using Homebrew to install terminal\-notifier is not recommended.
.SH "ON\-THE\-FLY COMMANDS"
.sp
While the app is (re)running, you can make things happen by pressing keys:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBr\fP \(em; restart (as if a file had changed)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBc\fP \(em; clear the screen
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBx\fP or \fBq\fP \(em; exit (just like control\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBp\fP \(em; pause/unpause filesystem watching
.RE
.sp
If you\(cqre backgrounding or using Pry or a debugger, you might not want these
keys to be trapped, so use the \f[CR]\-\-background\fP option.
.SH "SIGNALS"
.sp
The current algorithm for killing the process is:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
send [SIGTERM](\c
.URL "http://en.wikipedia.org/wiki/SIGTERM" "" ")"
(or the value of the \f[CR]\-\-signal\fP option)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if that doesn\(cqt work after 4 seconds, send SIGINT (aka control\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if that doesn\(cqt work after 2 more seconds, send SIGKILL (aka kill \-9)
.RE
.sp
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.
.SH "TROUBLESHOOTING"
.sp
If you are using \f[CR]zsh\fP as your shell, and you are specifying your \f[CR]\-\-pattern\fP as \f[CR]\fB*/\fP.rb\fP, you may face this error
.sp
.if n \{\
.RS 4
.\}
.nf
Errno::EACCES: Permission denied \- <filename>
.fi
.if n \{\
.RE
.\}
.sp
This is because \f[CR]\fB*/\fP.rb\fP gets expanded into the command by \f[CR]zsh\fP instead of passing it through to rerun. The solution is to simply quote (\(aq\(aq or "") the pattern.
i.e
.sp
.if n \{\
.RS 4
.\}
.nf
rerun \-p **/*.rb rake test
.fi
.if n \{\
.RE
.\}
.sp
becomes
.sp
.if n \{\
.RS 4
.\}
.nf
rerun \-p "**/*.rb" rake test
.fi
.if n \{\
.RE
.\}