watchman

Monitor files and trigger actions upon changes

TLDR

Infer the root directory of the project containing the specified directory, and watch its files and sub-folders for changes

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

Add a trigger to run a command when files with a specified filename pattern in a watched directory change

$ watchman -- trigger [path/to/watched_directory] [trigger_name] '[pattern]' -- [command]

List all watched directories

$ watchman watch-list

Delete a watch on a directory and its associated triggers

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

Delete all watched directories and triggers

$ watchman watch-del-all

List all triggers on a watched directory

$ watchman trigger-list [path/to/watched_directory]

Delete a trigger from a watched directory

$ watchman trigger-del [path/to/watched_directory] [trigger_name]

Temporarily stop watchman, until the next time you call a watchman command

$ watchman shutdown-server

SYNOPSIS

watchman [global-options] subcommand [args]

--help
    Display help and exit

--version
    Output version information

--json
    Emit output in JSON format

--no-pretty
    Disable pretty-printing of JSON

--logfile FILE
    Log to specified file

--log-level LEVEL
    Set log verbosity (0-6, default 4)

--sockname PATH
    Use custom socket path

--foreground
    Run daemon in foreground

--no-daemonize
    Don't daemonize (with --foreground)

--wait
    Wait for command completion

DESCRIPTION

Watchman is a filesystem monitoring tool developed by Facebook (now Meta) for detecting file changes efficiently. It uses kernel-level events like inotify on Linux to watch directories and trigger actions on modifications, creations, or deletions. Unlike polling-based tools, Watchman scales to large codebases by merging events, ignoring transient changes, and providing query capabilities via a JSON-based protocol.

Key use cases include build systems (e.g., Buck, Bazel), continuous integration, and development workflows where recompilation or testing is needed only on actual changes. It runs as a daemon, accessible via the watchman client CLI, which communicates over a Unix socket. Commands allow watching directories, listing triggers, querying file states by clock or time, and more. Watchman deduplicates events and settles the filesystem state before notifying, reducing noise in dynamic environments.

CAVEATS

Requires a running Watchman daemon (started automatically on first use). High directory counts may need config tweaks. Linux-specific inotify limits apply; use watchman watch-list to manage roots. Not for real-time critical apps due to settling delays.

COMMON SUBCOMMANDS

watch ROOT: Start watching directory.
unwatch ROOT: Stop watching.
trigger ROOT NAME *CMD: Run command on changes.
query ROOT --since @clock: JSON query for changed files.

STATE QUERIES

Uses named clocks for reproducible builds. watchman query supports expressions like path suffixes, time since, file size.

HISTORY

Developed by Facebook in 2013 for the Buck build system to handle massive monorepos. Open-sourced under Apache 2.0. Active maintenance by Meta; versions track feature additions like named cursors (v4.9+), Mercury query lang (v2021+). Widely used in React Native, Flow, and other tools.