Watchman — High-Performance File Watching Service by Meta

Introduction

Watchman is a file watching service developed by Meta (Facebook) that efficiently monitors large directory trees for file changes. It uses OS-level notifications (inotify, FSEvents, kqueue) to detect changes instantly and exposes a query API for tools to ask what changed since a given point in time. React Native, Jest, and Buck all rely on Watchman for fast incremental rebuilds.

What Watchman Does

• Watches directory trees using OS-native filesystem event APIs
• Maintains an in-memory index of all files with metadata (size, mtime, content hash)
• Supports query expressions to find files matching patterns, globs, or content hashes
• Triggers user-defined commands when matching files change
• Provides a Unix socket API and CLI for integration with build tools

Architecture Overview

Watchman runs as a long-lived daemon process that subscribes to OS-level file change notifications. It builds an in-memory snapshot of watched directories and updates it incrementally. Clients connect over a Unix domain socket and issue queries in a JSON-based protocol. The daemon coalesces rapid changes into batched notifications, reducing overhead on high-churn directories.

Self-Hosting & Configuration

• Watchman runs as a local user-level daemon; no root access required
• Configure global settings in /etc/watchman.json or ~/.watchman.json
• Set per-watch configurations like ignore patterns via .watchmanconfig in the project root
• Control idle timeout, IO priority, and maximum file count via CLI flags
• The daemon auto-starts on first watchman command and can be stopped with watchman shutdown-server

Key Features

• Handles repositories with millions of files efficiently via incremental indexing
• Content-aware queries using file hashes, not just mtime, to avoid false positives
• Subscription API for real-time streaming of change events to connected clients
• Saved state support for near-instant warm-start after daemon restart
• Cross-platform support for Linux, macOS, and Windows

Comparison with Similar Tools

• inotifywait — low-level Linux-only inotify wrapper; Watchman adds indexing, queries, and cross-platform support
• chokidar — Node.js file watcher library; Watchman is a standalone daemon with richer query capabilities
• fswatch — CLI file watcher; Watchman provides a queryable index and persistent daemon
• entr — runs commands on file changes; Watchman supports complex glob matching and subscriptions
• watchexec — Rust-based file watcher with smart defaults; Watchman excels on very large repositories

FAQ

Q: Why does React Native require Watchman? A: React Native's Metro bundler uses Watchman's query API to detect changed files instantly for fast hot reload.

Q: Does Watchman consume a lot of memory? A: Memory usage scales with the number of watched files. For typical projects it uses tens of MB; for million-file repos it can use more.

Q: Can Watchman replace inotify watches? A: Watchman uses inotify internally on Linux but adds indexing, batching, and a query API on top.

Q: How do I debug Watchman issues? A: Check the log at /usr/local/var/run/watchman/-state/log and use watchman log-level debug for verbose output.

Sources

• https://github.com/facebook/watchman
• https://facebook.github.io/watchman