watchman(1)

💖 watchman — the file watching service, bestie edition 💖

okay so you're here for watchman(1), the manual page for watchman, which is literally a file watching service. sit down, grab a boba, we're doing this 🧋✨

---

✨ NAME ✨

watchman — a file watching service. that's it, that's the name, she's simple and she's iconic 💅

---

🌸 SYNOPSIS 🌸

watchman [--OPTION ...]  COMMAND

yeah that's the whole shape of it — options, then a command, periodt.

---

🦋 DESCRIPTION 🦋

so watchman can recursively watch one or more directory trees — we also call those roots, iykyk.

and listen, this part matters: Watchman does not follow symlinks. she knows they exist, bestie, but they show up the same as any other file in its reporting. and she will wait for a root to settle down before she'll start triggering notifications or running commands. patience is a virtue 💅

Watchman is conservative, preferring to err on the side of caution — she considers files to be freshly changed when you start to watch them, or when she's unsure. no cap, she'd rather over-report than miss a thing.

you can query a root for file changes since you last checked, or for the current state of the tree. and — this is the good part — Watchman lets you subscribe to file changes that occur in a root. obsessed. 🫶

---

🎀 USAGE 🎀

here's the vibe. this example establishes a watch on a source directory, then sets up a trigger named buildme that will run a tool named minify-css whenever a CSS file is changed. the tool gets passed a list of the changed filenames. iconic behaviour fr fr.

watchman watch ~/src

and the single quotes around '*.css' are important, do not skip them:

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

(no bestie, that last sentence just ends there in the original. she said what she said. 💀)

---

💅 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 👑

the full roster, no skips, main character energy only:

• 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-make(1)

for more information, please refer the online documentation 🔥

---

and that's the whole page, bestie 🎀 this one's from the Linux corner of the world, dated 8 Oct 2019, and it's the watchman(1) page — mwah, slay, go watch some files 💖✨🦋