notify

notify is a Rust library that watches for filesystem changes across platforms, using the native OS mechanism on each — inotify on Linux, FSEvents or kqueue on macOS, ReadDirectoryChangesW on Windows, and kqueue on the BSDs — with a polling fallback everywhere else. It powers filesystem-watching in widely used tools including cargo-watch, rust-analyzer, watchexec, watchfiles, and Zed.

The project is a small Cargo workspace: alongside the core notify crate it ships notify-types (shared event types), notify-debouncer-mini and notify-debouncer-full (debouncing raw filesystem events into higher-level, coalesced change notifications), and file-id (a helper for stable file identity across renames).

What You Get

• A unified Watcher API backed by the fastest native mechanism on each platform (inotify, FSEvents, kqueue, ReadDirectoryChangesW)
• A polling-based fallback watcher for platforms or filesystems without native event support (e.g. network drives)
• Companion debouncer crates (notify-debouncer-mini, notify-debouncer-full) that coalesce bursts of raw events into stable, higher-level change notifications
• Shared notify-types event types so downstream crates can consume notify’s event model without depending on the full watcher implementation
• Battle-tested production usage inside cargo-watch, rust-analyzer, watchexec, watchfiles, and Zed

Common Use Cases

• Triggering a rebuild or hot-reload when source files change (as cargo-watch and watchexec do)
• Powering a language server’s file-change detection to keep an in-memory project index up to date
• Building a file-sync or backup tool that reacts to filesystem changes in near real time
• Debouncing noisy filesystem events (e.g. many rapid writes during a save) into a single coalesced notification
• Watching configuration files for changes to trigger a live application reload

Under The Hood

Architecture - The notify crate defines a Watcher trait in src/lib.rs/src/config.rs with platform-specific backend implementations selected at compile time: src/inotify.rs (Linux), src/fsevent.rs and src/kqueue.rs (macOS/BSD), src/windows.rs (ReadDirectoryChangesW), and src/poll.rs as a portable fallback. src/paths.rs normalizes path handling across these differing native APIs so callers see one consistent event shape regardless of backend. The separate notify-debouncer-full/notify-debouncer-mini crates sit on top of this trait, buffering raw events over a time window before emitting deduplicated, semantically richer notifications (e.g. collapsing a temp-file-then-rename sequence into a single “modified” event).

Tech Stack - A Cargo workspace (resolver v2) of six members (notify, notify-types, notify-debouncer-mini, notify-debouncer-full, file-id, examples) targeting Rust 1.88+, using platform-conditional dependencies (inotify, fsevent-sys/kqueue, windows-sys) selected per target OS. Linting is enforced via clippy.toml and dependency licensing/security via deny.toml.

Code Quality - The core notify crate spans roughly 10,800 lines across its platform backends, with a dedicated tests/ directory covering polling-hash behavior, race conditions around directory removal, and event serialization — deliberately targeting the flaky, timing-sensitive edge cases inherent to filesystem-event APIs. The project’s adoption by rust-analyzer, watchexec, and Zed as their filesystem-watching backend is itself a strong quality signal given how latency- and correctness-sensitive those consumers are.

API Design - The single Watcher trait keeps the core API small: construct a watcher, register paths, and receive events over a channel — with debouncing available as an opt-in add-on crate rather than baked into the core, keeping the base dependency light for consumers who want raw events. Cross-platform behavior differences (e.g. what counts as a “modify” event) are documented per-backend rather than fully abstracted away, which is an inherent trade-off of wrapping several genuinely different native APIs.