fswatch

Run a Bash command on file creation, update or deletion

$ fswatch [path/to/file] | xargs [[-n|--max-args]] 1 [bash_command]

$ fswatch [path/to/file] [path/to/directory] [path/to/another_directory/**/*.js] | xargs [[-n|--max-args]] 1 [bash_command]

$ fswatch [path/to/directory] | xargs [[-n|--max-args]] 1 -I _ echo _

$ fswatch --event [Updated|Removed|Created|...] [path/to/directory] | xargs [[-n|--max-args]] 1 [bash_command]

fswatch [OPTIONS] [PATH]...

-0, --print0
    Use the null character as a path separator for output, suitable for 'xargs -0'.

-d, --debounce
    Debounce events within the specified time window to avoid multiple triggers for a single logical change.

-e, --exclude
    Exclude paths matching the specified extended regular expression from monitoring.

-E, --include
    Include only paths matching the specified extended regular expression for monitoring.

-f, --format
    Specify the output format using a format string. Supports placeholders like '%p' (path), '%f' (flags).

-l, --latency
    Set the latency for coalescing events. Events occurring within this period are grouped (default: 0.1 seconds).

-m, --monitor
    Specify the monitor type to use (e.g., 'inotify', 'kqueue', 'fsevents', 'poll'). fswatch typically auto-detects the best one.

-n, --max-events
    Exit after a specified number of events have been received. Useful for single-shot operations.

-o, --one-shot
    Exit after the first event has been received. Alias for --max-events 1.

-r, --recursive
    Monitor directories recursively, including all subdirectories and their contents.

-t, --event-type
    Filter events by type. Can be used multiple times (e.g., -t Created -t Updated). Valid types include 'Created', 'Updated', 'Removed', 'Renamed', 'AttributeModified'.

-x, --exclude-recursive
    Exclude paths recursively from monitoring, preventing traversal into excluded directories.

-v, --verbose
    Enable verbose output, showing more details about events, monitor types, and internal operations.

PATH...
    One or more paths (files or directories) to monitor. If no paths are specified, the current directory is monitored.

fswatch is a powerful, cross-platform command-line utility designed to monitor changes in files and directories in real-time. It leverages native file system event APIs specific to the operating system it runs on, such as inotify on Linux, kqueue on macOS and BSD, and FSEvents on macOS. This allows fswatch to efficiently detect modifications, creations, deletions, and attribute changes without constant polling, thus minimizing CPU and resource consumption.

It's commonly used in development workflows for tasks like automatically recompiling code, restarting development servers, running test suites upon code changes, or triggering synchronization scripts. By default, fswatch prints the path of the changed file to standard output, making it easy to pipe its output to other commands or scripts for further processing. Its versatility and efficiency make it an invaluable tool for automation and continuous integration setups.

While highly efficient, fswatch does have some limitations:

Resource Limits: On Linux, the inotify subsystem has limits (e.g., max_user_watches, max_queued_events) which can be hit when monitoring an extremely large number of files or deeply nested directories. These limits can usually be increased via sysctl.

Temporary Files: Some text editors save changes by writing to a temporary file and then renaming or replacing the original. This can lead to Created and Removed events instead of just an Updated event for the original file.

Symlinks: Behavior with symbolic links can be complex, especially with recursive monitoring and exclusion/inclusion patterns, requiring careful configuration.

Polling Fallback: If native file system event APIs are unavailable or fail, fswatch may fall back to less efficient polling, which consumes more resources and might not detect changes instantaneously.

fswatch can report various types of file system events, allowing for fine-grained control over what triggers an action. Common event types include: Created, Updated, Removed, Renamed, MovedFrom, MovedTo, AttributeModified (e.g., permissions, timestamps), and SizeModified. You can filter for specific event types using the -t or --event-type option, specifying one or more types to receive only relevant notifications.

One of fswatch's key strengths is its broad cross-platform compatibility. It intelligently selects the most efficient native API available on the host operating system:
inotify on Linux
kqueue on macOS and BSD systems
FSEvents on macOS
ReadDirectoryChangesW on Windows
This ensures optimal performance and resource usage regardless of the environment, making it a reliable tool for development and automation across diverse systems.

fswatch was developed to provide a unified, cross-platform interface for file system event monitoring. It was designed to overcome the limitations of platform-specific tools and offer a consistent way for developers to react to file changes, especially important in a world where projects are often developed across different operating systems. Its initial development aimed to leverage the most efficient native APIs available on each system, making it more performant than simple polling solutions. While precise historical dates might be hard to pinpoint without diving deep into its source repository, its design philosophy is rooted in providing a robust and flexible tool for modern development workflows requiring automation and continuous integration.

inotifywait(1), watch(1), find(1)