watchman

Watch a directory

$ watchman watch [/path/to/dir]

$ watchman watch-list

$ watchman watch-del [/path/to/dir]

$ watchman watch-project [/path/to/project]

$ watchman find [/path/to/dir] -p ["*.js"]

$ watchman -- trigger [/path/to/dir] [triggername] ["*.js"] -- [command]

$ watchman shutdown-server

$ watchman version

watchman command [options] [arguments]

watchman is a file watching service that monitors directories and triggers actions when files change. It was designed for large codebases requiring efficient file change detection.
The daemon maintains inotify/FSEvents watches and records file changes. Clients query for changes efficiently - even with millions of files, queries return in milliseconds.
Triggers execute commands when matching files change. This enables automated testing, building, or syncing. Triggers can filter by file pattern and use templated commands.
The query system uses a JSON expression language for complex file matching. Queries can filter by name, type, size, modification time, and more. Results include file metadata.
Clock values track change history. Subscribing to changes since a clock enables incremental processing - only handling new changes rather than full scans.
Watchman integrates with build tools (Buck, Bazel), IDEs, and testing frameworks. It provides the file watching layer that other tools build upon.

watch PATH

Start watching directory.

Stop watching directory.

List all watches.

Watch project root.

Find files matching criteria.

Query files with expression.

Find files changed since clock.

Set up triggered command.

Remove trigger.

List triggers.

Set logging level.

Get watch configuration.

Stop watchman daemon.

Show version and capabilities.

Daemon must be running for watches. System limits on watched files may need increasing. Not all filesystems support efficient watching. Configuration persists across restarts. Memory usage grows with file count.

watchman was developed at Facebook (Meta) and released in 2012. It was designed to handle Facebook's massive codebase where inotify alone wasn't sufficient. The project became a foundation for various developer tools needing efficient file change detection.

inotifywait(1), entr(1), fswatch(1)