Skip to main content
Watchman logo


A file watching service

Watches files and records, or triggers actions, when they change.

Watchman exists to watch files and record when they change. It can also trigger actions (such as rebuilding assets) when matching files change.


  • Watchman can recursively watch one or more directory trees (we call them roots).
  • Watchman does not follow symlinks. It knows they exist, but they show up the same as any other file in its reporting.
  • Watchman waits for a root to settle down before it will start to trigger notifications or command execution.
  • Watchman is conservative, preferring to err on the side of caution; it considers files to be freshly changed when you start to watch them or when it is unsure.
  • You can query a root for file changes since you last checked, or the current state of the tree
  • You can subscribe to file changes that occur in a root


These two lines establish a watch on a source directory and then set up a trigger named buildme that will run a tool named minify-csswhenever a CSS file is changed. The tool will be passed a list of the changed filenames.

$ watchman watch ~/src
# the single quotes around '*.css' are important!
$ watchman -- trigger ~/src buildme '*.css' -- minify-css

The output for buildme will land in the Watchman log file unless you send it somewhere else.