watchman

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]

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

$ watchman watch-list

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

$ watchman watch-del-all

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

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

$ watchman shutdown-server

watchman [global-options] <command> [command-options] [arguments]

--help, -h
    Displays a help message and exits.

--version, -v
    Shows the program's version number and exits.

--sockname <path>
    Specifies the path to the Unix socket for communication with the watchman server. Overrides default socket paths.

--foreground
    Runs the watchman server in the foreground, useful for debugging.

--log-level <level>
    Sets the logging level for the server (e.g., debug, info, warning, error).

--json-output
    Formats the command's output as JSON, suitable for programmatic parsing.

watch <directory>
    Establishes a persistent watch on the specified directory. This is usually the first step to monitor a project.

find <directory> [options]
    Queries the watched directory for files matching specified criteria (e.g., name, size, time).

trigger <directory> <name> <command_array> [options]
    Defines a named trigger that executes a specified command when files change in the directory according to defined rules.

subscribe <directory> <name> [options]
    Subscribes to file changes in a directory, receiving real-time notifications, often used by long-running client processes.

watch-list
    Lists all directories currently being watched by the watchman server.

trigger-list <directory>
    Lists all triggers associated with a specific watched directory.

log <level> <message>
    Sends a custom log message to the watchman server's log output.

status
    Reports the health and current status of the watchman server.

shutdown-server
    Gracefully shuts down the running watchman server instance.

version
    Returns the version of the watchman server and the protocol it supports.

get-sockname
    Prints the path to the Unix socket that the watchman server is using.

watchman is an open-source, cross-platform file monitoring service developed by Facebook. It is designed to recursively watch one or more directory trees for changes and trigger actions when files are modified. Unlike simpler file watch utilities, watchman is built for performance and scalability, making it ideal for large codebases and complex build systems.

It uses native OS file system event APIs (like inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows) to efficiently detect changes. Its client-server architecture allows multiple clients to connect to a single watchman server instance, reducing resource overhead. It's commonly used by development tools like React Native, Yarn, and various build tools to enable fast incremental builds, live reloading, and real-time synchronization.

• Resource Usage: Can consume significant memory and CPU, especially with many watched directories or very active file systems. Careful configuration is advised for large-scale deployments.
• System Limits: Relies on OS-level file watch limits (e.g., inotify watches on Linux). These limits may need to be increased for large projects to prevent errors.
• Initial Scan: When a watch is established on a new directory, watchman performs an initial recursive scan, which can be time-consuming for very large directory trees.
• Permission Issues: Requires appropriate file system permissions to watch directories, create its socket, and write logs.
• Symbolic Links: Default behavior for symbolic links can sometimes lead to unexpected results; explicit handling might be needed depending on the specific use case.

watchman operates as a daemon (server) that maintains persistent watches and a separate command-line tool (client) that communicates with the server to establish watches, query for changes, or configure triggers. This separation allows multiple tools and processes to leverage the same file watching infrastructure without duplicating effort or consuming excessive resources.

One of watchman's most powerful features is its ability to define "triggers." A trigger is a command that watchman will execute automatically when specified file changes occur within a watched directory. This enables automated tasks like recompiling code, refreshing browser views, or running tests upon file modifications.

Designed to work across Linux, macOS, and Windows, watchman abstracts away the underlying operating system's specific file event mechanisms. This ensures consistent behavior and reliable file change detection for development teams working on different platforms.

watchman was developed by Facebook to address the performance challenges of building and developing large projects, particularly those involving JavaScript (like React Native) and other web technologies. Traditional file watching mechanisms often proved too slow or resource-intensive for the scale of Facebook's monorepos. It was open-sourced to provide a robust and efficient solution for the broader developer community, becoming a key component in many modern build workflows and developer toolchains.

inotifywait(1), find(1), ls(1), fswatch(1)