Command line and power tools

Knowing the moment a file changes

Updated 2026-08-08 · 4 min read

macOS already notices every file change — FSEvents powers Spotlight and Time Machine. fswatch hands that stream to your own scripts, which turns 'run this when anything changes' from a polling hack into one command.

Install and first watch

brew install fswatch
fswatch -o ~/Documents/Reports | while read n; do
  echo "changed at $(date)"
done

-o batches events into counts — one line per burst of changes — which is the mode scripts want. Without it, fswatch emits one line per event per file, and a single save from a modern app (write temp, rename, update metadata) floods the loop.

The debounce pattern

Real work belongs behind a settle delay, because file operations arrive in bursts:

fswatch -o --latency 5 ~/Sync/inbox | while read n; do
  sleep 2   # let the writer finish
  ~/bin/process-inbox.sh
done

--latency 5 batches five seconds of events; the sleep guards against processing a file mid-write. For copies of large files, the robust check is size stability — compare stat -f%z across a second, proceed when it stops moving.

Useful variations

• -e '\.tmp$' / -i '\.pdf$' — exclude and include by regex; watching

everything and filtering in your script wastes wakeups.

• -r — recursive is the default via FSEvents, but explicit when using the

slower kqueue monitor.

• Multiple paths in one invocation: fswatch -o A B C.

What event watching cannot promise

FSEvents coalesces: it tells you *something changed here*, reliably, but not always every individual event, and never *what content* changed — your script diffs or rescans to find out. Missed-while-not-running changes are also invisible; a watcher complements an occasional full scan rather than replacing it. (That pairing — live events plus periodic reconciliation — is exactly how indexing tools, Spotlight included, stay both fast and honest.)

Common questions

Does fswatch cost battery or performance?

Essentially none while idle — FSEvents pushes events; nothing polls. The cost is whatever your script does when triggered.

Why does one file save trigger several events?

Apps save via temp-file-and-rename, generating multiple operations. Use -o with --latency and debounce in the handler.