What Is Watchman, the File-Watching Tool Described on wezfurlong.org?

Updated

Watchman is a file-watching tool that monitors files and records information about them as they change. According to the description on wezfurlong.org, you can configure it to trigger build or test steps when files matching a pattern change, but its primary purpose is to answer queries about the status of a set of files instantly. It maintains a view of the filesystem kept in sync through kernel filesystem notification facilities, and that view is indexed so status queries return quickly.

What Watchman does

The site's summary breaks the tool's role into three parts:

  • Watching: it observes files and records information about them as they change.
  • Reacting: you can arrange for build or test steps to run in response to changes in matching files.
  • Querying: the main reason it was built is to return file status for a set of files instantaneously.

How it stays fast

Rather than scanning the filesystem on every request, Watchman maintains a view of the filesystem that is kept in sync using kernel filesystem notification facilities. That view is indexed, which is what makes quick status queries possible. In practice, this means a tool that needs to know "what changed?" can ask Watchman instead of walking the directory tree itself.

Where the description comes from

The account on wezfurlong.org is a short June 2013 post announcing Watchman on the Facebook Engineering blog. Wez Furlong describes it there as a project he worked on, and the post is filed under the site's "watchman" category. The site itself is his personal blog, which also hosts posts on other topics and links to his open source projects, publications, and mentoring services.

What to keep in mind

The page evidence covers the announcement and purpose of Watchman, not installation steps, configuration syntax, or current platform support. If you want to use it, treat the description above as the "what and why" and check the project's own documentation for the "how." The core idea to carry forward is simple: Watchman is a fast, indexed view of file changes that other tools can query and hook into, rather than a build system or test runner on its own.