---
name: "watchman"
section: "1"
platform: "linux"
package: "watchman"
version: "4.9.0-7+b2"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/watchman"
---

# watchman(1)

a file watching service

## NAME

watchman - a file watching service

## SYNOPSIS

**watchman** \[--OPTION ...\] COMMAND

## DESCRIPTION

**watchman** can recursively watch one or more directory trees (also referred to as roots).  Watchman does not follow symlinks; it knows they exist, but they show up the same as any other file in its reporting and it will wait for a root to settle down before it will start to trigger notifications or command execution. Watchman is conservative, preferring to err on the side of caution; it considers files to be freshly changed when you start to watch them or when it is unsure. You can query a root for file changes since you last checked, or the current state of the tree. Watchman allows you to subscribe to file changes that occur in a root.

## USAGE

The following example establishes a watch on a source directory and then sets up a trigger named buildme that will run a tool named minify-css whenever a CSS file is changed. The tool will be passed a list of the changed filenames.

-

  `watchman watch ~/src`

the single quotes around '\*.css' are important:

-

  `watchman -- trigger ~/src buildme '*.css' -- minify-css`

The output for buildme will land in the Watchman log file unless you send it somewhere else.  To use

**OPTIONS**

**-h, --help**

-

  `Show this help`

**--inetd**

-

  `Spawning from an inetd style supervisor`

**-v, --version**

-

  `Show version number`

**-U, --sockname=PATH**

-

  `Specify alternate sockname`

**-o, --logfile=PATH**

-

  `Specify path to logfile`

**--log-level**

-

  `set the log level (0 = off, default is 1, verbose = 2)`

**--pidfile=PATH**

-

  `Specify path to pidfile`

**-p, --persistent**

-

  `Persist and wait for further responses`

**-n, --no-save-state**

-

  `Don't save state between invocations`

**--statefile=PATH**

-

  `Specify path to file to hold watch and trigger state`

**-j, --json-command**

-

  `Instead of parsing CLI arguments, take a single json object from stdin`

**--output-encoding=ARG**

-

  `CLI output encoding. json (default) or bser`

**--server-encoding=ARG**

-

  `CLI<->server encoding. bser (default) or json`

**-f, --foreground**

-

  `Run the service in the foreground`

**--no-pretty**

-

  `Don't pretty print JSON`

**--no-spawn**

-

  `Don't try to start the service if it is not available`

**--no-local**

-

  `When no-spawn is enabled, don't try to handle request in client mode` `if service is unavailable`

**AVAILABLE COMMANDS**

      clock\
       debug-ageout\
       debug-contenthash\
       debug-drop-privs\
       debug-get-subscriptions\
       debug-poison\
       debug-recrawl\
       debug-set-subscriptions-paused\
       debug-show-cursors\
       find\
       flush-subscriptions\
       get-config\
       get-pid\
       get-sockname\
       list-capabilities\
       log\
       log-level\
       query\
       shutdown-server\
       since\
       state-enter\
       state-leave\
       subscribe\
       trigger\
       trigger-del\
       trigger-list\
       unsubscribe\
       version\
       watch\
       watch-del\
       watch-del-all\
       watch-list\
       watch-project

## SEE ALSO

[watchman-wait(1)](/watchman-wait/1.md), [watchman-make(1)](/watchman-make/1.md)

For more information, please refer the online documentation ⟨http://facebook.github.io/watchman/docs/cli-options.html⟩