Get-started with Watchman

Introduction

Watchman is a file-watching service by Meta (Facebook) that monitors files and triggers actions when they change. It’s commonly used in development environments to watch source files, run tests, or rebuild outputs automatically.

Basic syntax

watchman <command> [args...]

Some basic commands include:

• watch — start watching a directory
• trigger — run a command when files change
• query — check file states manually
• shutdown-server — stop the watchman daemon

Setup

Install Watchman

• macOS: brew install watchman
• Linux: follow instructions. Also see this.
• Windows: unofficial support via WSL or community ports

Triggers

Triggers let you run commands when files change. You define them using a command like:

watchman -- trigger /path/to/project trigger-name [patterns] -- command-to-run arg1 arg2

Example: Rebuild when JS changes

watchman -- trigger ~/my-app js-build '*.js' -- npm run build

Watchman will now watch all *.js files in ~/my-app and run npm run build on changes.

To see all watched paths:

watchman watch-list

To list active triggers:

watchman trigger-list /path/to/project

To delete a trigger:

watchman trigger-del /path/to/project trigger-name

To delete a watch:

watchman watch-del /path/to/project

Configuration file: .watchmanconfig

Place a .watchmanconfig file in the root of a watched directory:

{
  "ignore_dirs": ["node_modules", ".git"],
  "settle": 200
}

• ignore_dirs: folders to exclude from watching
• settle: debounce delay in milliseconds (for bursty events)

Notes

• Watchman doesn’t handle recursive globs like **/*.js. Use suffixes or extensions in expressions.
• Use with care in large repos — exclude node_modules and .git to reduce overhead.

---

References

• https://facebook.github.io/watchman/