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 [options] command [command-options]

--help
    Show help message and exit.

--version
    Show version information and exit.

watch
    Add a directory to watch list.

unwatch
    Remove a directory from watch list.

watch-del-all
    Remove all watched roots.

since
    Query for changes since a specific time.

trigger
    Define file change triggers.

shutdown-server
    Stop the watchman server.

find
    Search for files matching certain criteria.

DESCRIPTION

watchman is a file system monitoring service that watches files and records when they change. It enables applications to react to changes in the file system without polling, providing efficient and real-time updates. It's primarily used by tools like build systems, code editors, and continuous integration servers to automatically trigger actions when source code or configuration files are modified. Watchman uses a combination of kernel APIs and polling strategies to detect changes, and provides a command-line interface and a client library for interacting with its monitoring capabilities. It aims to be efficient, reliable, and scalable, even in environments with a large number of files.

CAVEATS

Watchman requires appropriate file system permissions to monitor directories.
Performance may degrade when watching very large directory trees or when the system experiences high file system activity.
Certain file system events may not be detected reliably on all platforms.

JSON INTERFACE

Watchman exposes its functionality through a JSON-based interface. Clients can communicate with the watchman server by sending JSON commands and receiving JSON responses. This allows for programmatic interaction with the service.

TRIGGER CONFIGURATION

Triggers are used to define actions that should be taken when files change.
Triggers can be configured to execute commands, send notifications, or perform other tasks.

HISTORY

Watchman was created by Facebook and later open-sourced. It was developed to address the limitations of traditional file system monitoring tools, particularly in large-scale codebases. It has become a popular tool for build systems and other development tools that require real-time file system change notifications.