Watchy

Run commands when paths change.

Install

You'll need to install Node.js to use Watchy. Node comes packaged with npm, which is Node's package manager, and the preferred method of installing Watchy. After installing Node, simply type

npm install -g watchy

and you should have the watchy command available!

Usage

Usage: watchy [options] -- <command> [args...]

Run commands when paths change.

Options:
  -V, --version                   output the version number
  -d, --debounce [seconds]        trigger a change at most every [seconds] seconds
  -k, --keep-alive                restart the process if it exits
  -r, --restart [string]          send [string] to STDIN to restart the process
  -R, --no-restart-after-signal   disable process restart after being signaled and exited
  -s, --silent                    only output errors
  -S, --no-init-spawn             prevent spawn when the watcher is created
  -t, --shutdown-signal [signal]  use [signal] to shut down the process (default: "SIGTERM")
  -T, --reload-signal [signal]    use [signal] to reload the process (defaults to shutdown
                                  signal)
  -w, --watch [pattern]           watch [pattern] for changes, can be specified multiple times
  -W, --wait [seconds]            send SIGKILL to the process after [seconds] if it hasn't
                                  exited
  -h, --help                      display help for command

The watch patterns are extglob format.

Examples

# The simple case
watchy -w 'lib/**/*' -- say "The lib directory changed."

# Piping works as well
watchy -w 'styles/**/*.less' -- bash -c "lessc styles/main.less | autoprefixer -o .tmp/styles/main.css"

# Keep a process alive, restarting it as soon as it exits or "server.js"
# changes.
watchy -kw server.js -- node server.js

# Watch every file except dotfiles, the node_modules folder, and JSON files.
# NOTE: Listen to as few files as possible for better performance.
watchy -w . -i '/\.|/node_modules|\.json$' -- node server.js

# Tick tock!
watchy -ks -- bash -c 'date && sleep 1'

# Tick tock (annoying version)!
watchy -ks -- bash -c 'say "In case you were wondering, it is `date`" && sleep 5'

# The envvar WATCHY_PATHS is passed to the process.
watchy -S -w '**/*' -- bash -c 'echo $WATCHY_PATHS changed'
# => modified /Users/casey/Documents/code/watchy/README.md

Note: If you're using watchy for help with preprocessing, I'd recommend checking out my cogs project that is highly optimized for that case with in-memory processed file caching, directives, AMD support, and much more.

SIGTERM

By default, watchy will send SIGTERM to the running process after a change and wait for it to exit gracefully. By sending the --wait|-W n option, you can tell watchy to forcefully SIGKILL the process after n seconds. In general, you should try to clean up connections in your processes like so:

process.on('SIGTERM', () => {
  server.close();
  db.disconnect();
  redis.quit();
  // etc...
});

Node API

As of 0.9.0 watchy exposes a Node.js API.

import { watch } from 'watchy';

watch({
  debounce: 0.5,
  onChange: paths => console.log(paths),
  patterns: ['js/**/*.js', 'css/**/*.css'],
});

Changelog

0.12.3

• debounce option added to watch

0.12.0

• A file poller was added to pick up file changes that may have been missed by file system events. This adds a small CPU overhead but means changed files will all eventually be detected.
• BREAKING
  • A short debounce time was added to the onChange callback to prevent duplicate changes triggering in rapid succession.
  • The onChange callback now receives paths instead of a single path.
  • The WATCHY_PATH envvar has been renamed to WATCHY_PATHS and contains a comma-separated list of all paths changed

0.11.0

• Add TS definition file
• BREAKING
  • Default export converted to named watch export.
  • chokidar dependency dropped. Uses fs.watch now.
  • usePolling option dropped
  • onError callback removed. watch will fail synchronously if a watcher is not able to created on the base directory.
  • onChange callback changed from (options: { action: string; path: string }) => void to just (path: string) => void. Action was often incorrect/inconsistent.
  • The CLI remains the same except for the removal of --use-polling

0.10.0

• Upgrade to ES modules.
• Drop -n/--no-color flag, determine color based on TTY. Use FORCE_COLOR=0/1 envvar override color support.

0.9.7

• @atom/watcher is likely being discontinued, so switching to chokidar@3

0.9.6

• Fix typo in usage output.

0.9.1

• Fix package.json main entry.

0.9.0

• File watching is now handled by the @atom/watcher package.
• BREAKING Removed i/--ignore option.
• BREAKING -w/--watch arguments are now specified as extglob patterns.

0.7.1

• Add -K/--kill-signal option to override SIGTERM with a custom signal.
• Add -m/--multiple flag to allow the kill signal to be sent to the process multiple times.

• -K and -m make upgrading a process on change possible, for example

  watchy -w /etc/nginx/nginx.conf -mK SIGHUP -- nginx

  will upgrade nginx whenever the config file is changed.

0.7.0

• BREAKING The path passed to -w/--watch is no longer split on comma. This was a bit of a lazy way to handle multiple paths and inherently prevented the possibility of watching a path with a comma. From 0.7.0 on, specify multiple paths to watch by passing multiple -w/--watch flags.

  For example, instead of

  watchy -w bin,lib,CHANGELOG.md -- ls

  use

  watchy -w bin -w lib -w CHANGELOG.md -- ls

0.6.6

• Add a changelog.
• Add --no-init-spawn option to optionally not run the command on start, but only after changes.