# Watchman — High-Performance File Watching Service by Meta

> Watchman is an open-source file watching service by Meta that monitors filesystem changes and triggers actions. It powers fast incremental builds in React Native, Buck, and other build systems.

## Install

Save as a script file and run:

# Watchman — High-Performance File Watching Service by Meta

## Quick Use
```bash
# Install on macOS
brew install watchman

# Install on Ubuntu
sudo apt-get install watchman

# Watch a directory for changes
watchman watch /path/to/project

# Trigger a command when .js files change
watchman -- trigger /path/to/project buildme '*.js' -- npm run build
```

## 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/<user>-state/log and use watchman log-level debug for verbose output.

## Sources
- https://github.com/facebook/watchman
- https://facebook.github.io/watchman

---
Source: https://tokrepo.com/en/workflows/asset-07270d28
Author: Script Depot