Watchman is a file-watching service developed by Meta, designed to monitor files and directories efficiently. It is designed as a language-agnostic server for file watching, and standardizes file monitoring for diverse workflows, making it a powerful choice for complex, multi-language projects. This contrasts with language-specific tools like nodemon for Node.js or the watch mode in cargo.
Watchman operates as a client-server system, where a long-running server monitors the file system and clients issue commands or queries to interact with the server. If the server is not started, watchman commands start the server in process. The client and the server typically communicate over unix domain sockets or Windows pipe exchanging JSON-encoded data.
Watchman registers watches directly in the kernel (e.g., using inotify or fanotify) and uses clock values as unique identifiers to track changes over time. Clock values are robust against issues like system clock drift, ensuring reliable change tracking.
A powerful query language allows users to ask detailed questions about the file system’s state, including query clock values. The query language also allows to specify which metadata to return, such as file size, last modification time, and permissions. This is especially useful for tasks like caching or dependency tracking.
Example query: find all .js files that have changed since a specific clock value:
{
"expression": ["allof", ["match", "*.js"], ["since", "c:12345"]],
"fields": ["name", "mtime"]
}Example subscription: subscribe to .js file changes in a directory:
{
"command": ["subscribe", "/path/to/project", "my-subscription", {
"expression": ["match", "*.js"],
"fields": ["name", "mtime"]
}]
}