emcrisostomo/fswatch
Fswatch
fswatch is a cross-platform file change monitor that watches files and directories for modifications using the native event API of each operating system. It functions as a multi-backend file watcher library that selects from platform-specific backends such as inotify, kqueue, and FSEvents, with a polling fallback when no native API is available. The tool groups multiple file changes into a single event batch and triggers one command per batch, while also executing user-specified commands each time monitored files or directories are modified.
The project applies include, exclude, event-type, and traversal filters to reduce noise before triggering actions, and it outputs file paths as they change with optional null-delimited output for safe piping into shell scripts. It provides C language bindings that expose file monitoring functionality to any language supporting a C foreign function interface, with thread-safe session management that maintains per-thread state so concurrent watchers operate independently. The monitor uses a callback-driven event delivery model, a conjunctive filter pipeline, and a factory pattern to instantiate the correct platform monitor implementation.
Additional capabilities include latency tuning, recursive directory watching, event type filtering, and configurable output formats with event flags and timestamps. The project supports path filtering through include/exclude patterns, extension matching, and traversal pruning to reduce noise from unwanted directories. It can be installed via package managers, built from source archives, or compiled from a repository clone using the GNU Build System or CMake.
Features
- File Change Batch Processors - Groups multiple file changes into a single event batch and triggers one command per batch.
- Cross-Platform File Change Monitors - Watches files and directories for modifications across macOS, Linux, BSD, Solaris, and Windows using native event APIs.
- File System Monitor - Chooses from multiple platform-specific file change notification APIs or a polling fallback.
- File-Change-Triggered Commands - Executes a user-specified command each time monitored files or directories are modified.
- Event-Filtering - Applies include, exclude, event-type, and traversal filters to reduce noise before triggering actions.
- Multi-Backend - Selects from platform-specific backends such as inotify, kqueue, and FSEvents to monitor file changes.
- File Monitoring Bindings - Provides C bindings that expose file monitoring to any language with a C FFI.
- File Event Filter Pipelines - Applies include, exclude, event-type, and traversal filters to reduce file change noise.
- Path-Based View Filtering - Includes or excludes files and directories from monitoring using path-based patterns.
- Batch Event Processors - Groups multiple file change notifications into a single batch for optimized downstream processing.
- Platform Monitor Factories - Instantiates the correct platform-specific filesystem monitor using a factory method.
- Event-Driven Callbacks - Delivers file change events to user-defined callback functions during monitoring sessions.
- Recursive Directory Watchers - Monitors a directory tree recursively and captures changes to files created after the watcher starts.
- Traversal Pruning and Event Filters - Prevents descent into noisy directories and emits only events matching application source patterns.
- File Event Filters - Applies include, exclude, event-type, and traversal filters to suppress irrelevant file changes.
- File System Monitors - Watches files and directories for modifications using the native event API of the host operating system.
- File System Watchers - Uses the native event API of each operating system to report file and directory modifications.
- Thread-Safe Monitoring Sessions - Maintains per-thread state so concurrent file watchers operate independently without interference.
- File System Backend Abstractions - Selects the optimal native file system event API for each operating system through a unified interface.
- File Change Batching - Groups multiple file changes into a single event batch to reduce overhead for rebuilds or test reruns.
- Live Changed File Streams - Prints file paths as they change with null-delimited output for safe shell pipeline consumption.
- Change-Based Path Filtering - Prints file paths as they change with optional null-delimited output for safe piping into shell scripts.
- Filesystem Event Filters - Applies include, exclude, event-type, and traversal filters to reduce noise before triggering automated actions.
- File System Polling Fallbacks - Provides a polling fallback using stat() calls when no native file system event API is available.
- Null-Delimited File Path Streams - Outputs file paths with null delimiters for safe shell pipeline consumption.
- File Monitoring C Bindings - Provides C language bindings that expose file monitoring functionality to any language supporting a C foreign function interface.
- Per-Thread Monitoring Sessions - Maintains per-thread monitoring state so concurrent watchers operate independently.
- Factory Method Patterns - Uses a factory method to instantiate the correct platform-specific file monitor implementation.
- Filesystem Event Type Filters - Filters change notifications based on the type of filesystem event, such as creation, modification, or deletion.
- File Monitoring Sessions - Starts a file system monitor that gathers change events and delivers them to a callback until the session is stopped.
