Usage examples

Turn file system changes into reliable shell pipelines.

Start with paths, then add batching, filters, record formatting, or an explicit monitor when your workflow needs more control.

basic-watch
$ fswatch -r src include
src/main.cpp
include/fswatch.hpp

Common workflows

Each example is intentionally small enough to paste into a shell script and adapt.

Watch one directory

Print each changed path as fswatch receives it.

$ fswatch ~/project

Watch recursively

Observe a tree and include files created after fswatch starts.

$ fswatch --recursive ~/project

Run once per batch

Use count mode when event details are not needed.

$ fswatch -o src include \
  | xargs -n1 -I{} make test

Use null-delimited output

Handle paths with whitespace safely in shell loops.

$ fswatch -0 ~/project \
  | while IFS= read -r -d '' path; do
      printf 'changed: %s\n' "$path"
    done

Select a monitor

Override the default backend when you need a specific platform API.

$ fswatch --monitor kqueue_monitor ~/project
$ fswatch --list-monitors

Filter paths

Ignore build output and include only source-like paths.

$ fswatch -r . \
  --exclude='(^|/)build/' \
  --include='\.([ch]pp|h)$'

Prune noisy trees

Skip expensive directories during recursive traversal instead of only filtering their events.

$ fswatch -r ~/project \
  --prune='(^|/)(\.git|node_modules|vendor)$'

Conjunctive filters

Use conjunctive filter mode when include rules should choose the files you care about and exclude rules should still be able to subtract noisy matches.

Watch only selected extensions

Report changes to C and C++ source files without first excluding every path.

$ fswatch -r --filter-mode=conjunctive . \
  --include='\.([ch]pp|h|c)$'

Include source, exclude lockfiles

Keep editor lockfiles and temporary files out even when they match the included extension.

$ fswatch -r --filter-mode=conjunctive src \
  --include='\.(c|h)$' \
  --exclude='(^|/)\.#' \
  --exclude='~$'

Rebuild docs from source changes

Watch documentation sources while subtracting generated output and local build products.

$ fswatch -o -r --filter-mode=conjunctive docs \
  --include='\.(md|rst|texi)$' \
  --exclude='(^|/)(_build|html|pdf)/' \
  | xargs -n1 -I{} make docs

Filter events and prune traversal

Do not descend into dependency trees, then emit only application source events.

$ fswatch -r --filter-mode=conjunctive ~/project \
  --prune='(^|/)(\.git|node_modules|vendor)$' \
  --include='\.(js|ts|css)$' \
  --exclude='(^|/)dist/'

Event flags and formats

Use event flags, timestamps, and custom record formats when the consumer needs more than a changed path. 

$ fswatch --event-flags --timestamp ~/project
$ fswatch --format '%p %t %f' ~/project

Latency tuning

The latency setting controls how frequently fswatch delivers changes. Larger values can reduce overhead for noisy trees. 

$ fswatch --latency=2.5 ~/project

For complete option semantics, read the current release manual from the documentation hub. The examples here focus on common command-line workflows.

Open documentation