inotify-wait

Run a command when a file changes

$ while inotifywait [path/to/file]; do [command]; done

Be quiet about watching for changes

$ while inotifywait --quiet [path/to/file]; do [command]; done

Watch a directory recursively for changes

$ while inotifywait --recursive [path/to/directory]; do [command]; done

Exclude files matching a regular expression

$ while inotifywait --recursive [path/to/directory] --exlude '[regex]'; do [command]; done

Wait at most 30 seconds

$ while inotifywait --timeout [30] [path/to/file]; do [command]; done

Only watch for file modification events

$ while inotifywait --event [modify] [path/to/file]; do [command]; done

inotifywait [OPTIONS] FILE...
inotifywait [OPTIONS] --fromfile FILE

-h, --help
    Displays help information and exits.

-v, --verbose
    Prints more verbose information about the events. This includes cookie numbers for move events.

-q, --quiet
    Suppresses output to standard output, only exit status is significant.

-m, --monitor
    Keeps monitoring for events indefinitely rather than exiting after the first event. Requires an explicit signal to terminate.

-r, --recursive
    Monitors directories recursively. This adds all subdirectories to the watch list.

-t , --timeout
    Specifies a timeout in seconds. If no event occurs within this period, the command exits with a non-zero status. A value of 0 means no timeout.

-e ,,..., --event ,,...
    Specifies a comma-separated list of events to watch for. If omitted, all events are watched. Common events include: access, modify, attrib, close_write, open, create, delete, move, delete_self.

-o , --outfile
    Prints events to the specified file instead of standard output.

--csv
    Outputs events in CSV (Comma Separated Values) format, suitable for parsing by other programs.

--fromfile
    Reads files and directories to watch from the specified file, one path per line. Ignores other paths on the command line.

--format
    Specifies the output format for events using a format string. Supported format specifiers include: %w (watched path), %f (filename), %e (event names), %T (time stamp), %Xe (event codes). Default: '%w %f %e'.

--timefmt
    Specifies the format for the %T time specifier in --format. Uses strftime(3) format codes.

--exclude
    Excludes events for files matching the given shell-style glob pattern. The pattern is applied to the filename part of the path.

--excludei
    Similar to --exclude, but the pattern matching is case-insensitive.

inotifywait is a command-line utility that waits for specified filesystem events to occur within a directory or a set of files. It leverages the Linux kernel's inotify interface, which provides a mechanism to monitor filesystem events like file creation, deletion, modification, access, moving, and attribute changes. When an event occurs, inotifywait prints the event details (e.g., the watched path, event type, and filename) to standard output and then exits, unless the --monitor option is used, in which case it continues watching. This makes it particularly useful for scripting, allowing other commands or scripts to react automatically to changes in the filesystem. It's part of the inotify-tools package.

1. Kernel Limits: The number of inotify watches and user file descriptors are limited by kernel parameters (e.g., fs.inotify.max_user_watches, fs.inotify.max_user_instances, fs.inotify.max_queued_events). Monitoring a very large number of files or directories recursively can exceed these limits.
2. Event Atomicity: Inotify events are not necessarily atomic. For example, a single file copy operation might generate multiple create, modify, and close_write events.
3. Recursive Monitoring: When using -r, all new subdirectories created within a watched directory are automatically watched. However, moving a directory from outside into a watched tree might not trigger watches for its contents immediately, depending on the kernel version and specific operation.
4. Temporary Files: Many applications save files by writing to a temporary file and then moving it over the original. This often results in create and moved_to events rather accurate than modify events on the original file.

access: A file was read.
modify: A file was written to.
attrib: Metadata changed (permissions, timestamps, etc.).
close_write: A file opened for writing was closed.
close_nowrite: A file not opened for writing was closed.
open: A file was opened.
moved_from: A file/directory was moved from the watched directory.
moved_to: A file/directory was moved into the watched directory.
create: A file/directory was created within the watched directory.
delete: A file/directory was deleted within the watched directory.
delete_self: The watched file/directory itself was deleted.
unmount: The filesystem containing the watched file/directory was unmounted.

0: An event was received, or the command was terminated normally while monitoring (e.g., via SIGINT).
1: An error occurred (e.g., invalid arguments, cannot open file, kernel limits reached).
2: A timeout occurred before any event was received (only when --timeout is used).

The inotify API was introduced into the Linux kernel in version 2.6.13, released in 2005. The inotify-tools package, which includes inotifywait and inotifywatch, was developed shortly after to provide user-space utilities to interact with this new kernel feature, making it accessible for scripting and system monitoring tasks. Its development was driven by the need for more efficient and robust real-time filesystem monitoring than older methods like polling or kernel hacks.

inotifywatch(1), inotify(7), ls(1), find(1), tail(1)