--- name: "rerun" section: "1" platform: "linux" package: "rerun" version: "0.14.0-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rerun" --- # rerun(1) run programs and restarts them on filesystem changes ## 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\]( \)? 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 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 \ 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:` ``` 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](`` )` `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 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](`` )` `(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](`` ).` ### 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 - ``` **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 ```