Off The Grid
   Simple listserv
   xml tools
Karel as an adult


I wrote this little utility about half a year ago to scratch my own itch. Now I remembered to write it up.

What is it?

fswatch basically just watches a directory and whatever is underneath for changes. When a file appears, disappears, is renamed or changed, then a given command is run. Is this useful? Yes, if your daily work consist of coding, and if you want this wonderful thing called "continous builds" and "continuous tests" without having to retype commands. When using fswatch your build auto-restarts whenever you make a change to one of your source files.

How do I get it?


A few ideas of why fswatch might be handy:

Running make in the current directory

You have your wonderful program under ~/myprog/src and want to run the makejob in this directory whenever you change something. The invocation is:
cd ~/myprog/src
fswatch make
What happens here, is that fswatch monitors the current directory (~/myprog/src because you just cd'd into it) and runs its argument, make, whenever changes are seen. You'd probably want to run this in a separate terminal, because fswatch keeps running until you interrupt it using ^C.

Running your tests when something changes

Say you have a shell script ~/src/myprog/ that you want to re-run when you add or modify a testfile under ~/src/myprog/tests/. Then you can use:
cd ~/src/myprog
fswatch --dir tests/
What happens here, is that due to --dir tests/, fswatch will monitor the subdirectory tests/. As before, when changes are seen, it will run the given command.

Restarting a long running program

You're developing a program that is meant to run forever, say a logfile surfer. You want to tell fswatch to rebuild and restart it when a source file under ~/src/mylogsurfer is changed. You can use:
fswatch --timeout 10 --dir ~/src/mylogsurfer -- \
       sh -c 'make -C ~/src/mylogsurfer &&
              ~/src/mylogsurfer/mylogsurfer /var/log/*log'
What this means, is:

Other program options

When you start fswatch without arguments or with flag --help, then you get to see the usage information. This might be similar to something like this (though maybe now there's a more recent version that is slightly different):
This is fswatch 1.00, a file system watcher.
Written by Karel Kubat  2015 ff., distributed under GPLV3.
See for information and sources.

Usage: fswatch [FLAGS] COMMAND [ARGS]
The current direcotry is watched, and COMMAND [ARGS] is run when changes
are seen.

Accepted general flags:
  --                      ends flags, useful when you have -options in ARGS
  --help, -h:             this help
  --dir DIR, -d DIR       watches DIR instead of current directory
  --silent, -s            decreases verbosity

Flags related to file system polling:
  --dir DIR, -d DIR       watches DIR instead of current directory
  --interval SEC, -i SEC  poll interval of the filesystem, default 1

Flags for restarting COMMAND:
  --timeout SEC, -t SEC   restarts CMD when changes are seen but CMD has
                          been running longer than SEC seconds
  --killwait SEC, -k SEC  waits SEC secs between delivering signals SIGTERM,
                          SIGQUIT and SIGKILL to COMMAND, useful to allow
                          a slow graceful stop, default 1

How it works

fswatch simply periodically checks the file system to see whether something's changed. Yes, there are event-driven solutions for this (like dnotify or inotify), but these are OS-specific; while I need this to work on any Unixy environment. In short, I found that polling with an interval of 1 second works actually just fine.

I might rewrite fswatch to optimize for events, but don't hold your breath ;-) Remarks, bug reports etc. are as always welcome at

Similar Tools: Jay's Watcher

I received a nice heads-up from good buddy Jay about his own similar watcher at As far as I can tell, the two are similar, but: Check it out for yourself.