How to Use fswatch

Basic Usage

fswatch syntax is the following:

$ fswatch [options] [paths] ...

fswatch will then output change events to standard output. By default, only the affected file name is printed. However, many options are available to format the event record, including:

• The possibility of adding the event timestamp.
• The possibility of adding the event mask in both textual and numerical form.

Piping fswatch Output to Another Process

Very often you wish to not only receive an event, but react to it. The simplest way to do it is piping fswatch output to another process. Since in UNIX and UNIX-like file system file names may potentially contain any character but NUL (\0) and the path separator (/), fswatch has a specific mode of operation when its output must be piped to another process. When the -0/--print0 option is used, fswatch will use the NUL character as record separator, thus allowing any other character to appear in a path. This is important because many commands and shell builtins (such as read) split words and lines by default using the characters in $IFS, which by default contains characters which may be present (although rarely) in a file name, resulting in a wrong event path being received and processed.

Probably the simplest way to pipe fswatch to another program in order to respond to an event is using xargs:

$ fswatch -0 [opts] [paths] | xargs -0 -I {} [command]

This command performs the following operations:

• fswatch -0 will split records using the NUL character.
• xargs -0 will split records using the NUL character. This is required to correctly match impedance with fswatch.
• xargs -I {} will run the command once per record, substituting occurrences of {} in command with the parsed argument. If the command you are running does not need the event path name, just delete this option and add -n 1 to ensure the command is run once per path. If you prefer using another replacement string, substitute {} with yours.

Bubbling Events

An often requested feature is being able to receive a single event "per batch", instead of receiving multiple events. This use case is implemented by the -o/--one-per-batch option which tells fswatch to dump a record containing the number of received events, without any other detail:

$ fswatch -or /path/to/watch
1
10
[...]

This is useful if, for example, you want to respond to change events in a way which is (or can easily be) path-independent (because you are not receiving any event detail) and you prefer to "bubble" events together to reduce the overhead of the command being executed. A typical case is a directory synchronisation job whenever some files change.

Receiving a Single Event

Another requested feature is the possibility of receiving a single event and exit. This is most useful when existing scripts processing events include the restart logic of fswatch. This use case is implemented by the -1/--one-event option:

$ fswatch -1 /path/to/watch
/path/to/watch
$