Run arbitrary commands when files change

bitbucket/overview | download 2.8

EXEC mode

Recompile if a source file changes

$ find . -name '*.c' | entr make

FIFO mode

Convert individual Markdown files to HTML if they're modified

$ ls *.md | entr +notify &
$ while read F; do
>   markdown2html $F
> done < notify


Interactive SQL: OGG (47.0M, theora-vorbis) | WEBM (14.2M, vp8-vorbis)

Theory and Operation

The Event Notify Test Runner is a general-purpose UNIX utility intended to make rapid feedback and automated testing natural and completely ordinary.

Some graphical applications such as the PostScript/PDF viewer gv ship with a -watch option with reloads the document whenever the source file is modified. This is useful, but it's even better for applications to provide a programmatic means of refreshing the display. The browser add-on LiveReload has attempted to solve this problem for web developers by injecting JavaScript that listens on a web socket. The solution doesn't need to be this complex, indeed web pages can be opened or reloaded in xombrero using a a UNIX socket

$ ls *.css *.html | entr xombrero -e "reload"

It's not uncommon for modern web frameworks to continuously hunt for file system changes and refreshes the page when run in single threaded or standalone mode. Contrast this with common daemons which simply respond to signals. The following will reload nginx every time it's configuration is modified

$ ls /etc/nginx/nginx.conf | entr pkill -HUP nginx

In general, entr avoids special purpose options that can easily emulated using inline commands, for example one-shot mode can be emulated by running sh -c 'kill $PPID'. However, the need to kill and restart a process is a very common development task, so an auto-reload feature was added in the 1.9 release, and is enabled using the -r flag

$ ls *.rb | entr -r ruby main.rb

This will,

  1. immediately start the server
  2. block until any of the listed files change
  3. terminate the background process
  4. wait for the server to exit before restarting

Unlike guard, entr is a zero-configuration tool with no external build or runtime dependencies. The interface to entr is not only minimal, it aims to be simple enough to create a new category of ad hoc automation. These micro-tests reduce keystrokes, but more importantly they emphasize the utility of automated checks.

Tightening the edit-debug feedback loop requires a tool that is tuned for one task. inotifywait is lightweight, but it only works on Linux, and it's general feature set doesn't provide a direct means of saying “run this command if any of these files change”. This could be scripted, but there are a number of significant conditions to contend with:

  1. Many applications attempt to make the file save operation atomic by writing a new file and then removing the original. entr deals with this by closing the old file descriptor and reopening it using the same pathname. Since there is a small delay while the new file is renamed, we must wait for the new file to appear before running the supplied command and attempting to watch the new file.
  2. File change events that occur while the utility is running need to be processed so as to ensure that files that have been replaced are monitored, however it's natural to continue editing files while a task such as system tests are running. entr identifies this condition and will not re-run the utility if the file change events occured while waiting for the child process to end.
  3. It's not uncommon for version control software to update a large set of files when they're submitted, but we don't want to spawn a new task for every file that is modified, and we don't want to start a build until then entire operation is complete. To cope with this behavior entr repeatedly probes for subsequent events, and only executes the utility when the kernel returns with no results after a short timeout.
  4. The events reported when saving files on an NFS mount are different than than those of a local file system. On Linux an inotify may report IN_MOVE_SELF|IN_DELETE_SELF instead of IN_MODIFY|IN_CLOSE_WRITE and on BSD kqueue may report NOTE_RENAME|NOTE_DELETE instead of NOTE_WRITE|NOTE_EXTEND.
  5. A race condition exists when executing a script that is also under watch since a script cannot be executed while another process has it open for write. Rather than allowing the enigmatic error “Text file busy”, entr retries the execution.
  6. On Linux editors that use the Gnome's GIO may write to a file and then subsequently delete it. To deal with this entr consolidates events over 50ms before responding.
  7. In some cases an editor will rename a file without removing it. This occurs the first time a file is saved in Vim if the backup option is set. To deal with this events must be explicitly unregistered to prevent the kernel from tracking changes to backup files.

Finally, FIFO mode provides a means creating more sophisticated scripts by relaying the names of altered filenames through a named pipe. The watch script is a nice example of this use case.

Reducing Friction

entr adheres to the principle of separation of concerns, yet the reload (-r) option was added to solve a common use case that would otherwise require some careful scripting. Other special-purpose flags were added because they reduce highly repetitive actions or reduce friction.

One of the most repetitive actions was to clear the screen before running tests; hence the -c flag:

$ find src/ | entr -c ./test.sh

The special /_ argument (somewhat analogous to $_ in Perl) provides a quick way to refer to the first file that changed. When a single file is listed this is a handy way to avoid typing a pathname twice:

$ echo /path/to/my.sql | entr psql -f /_

Feedback Panes

I've been writing as if incorporating automated responses can be accomplished without special demands on the UNIX development environment, but in practice the ability to split a window into multiple panes is the key to making this workflow sing. If your window manager doesn't give you this capability a terminal multiplexer such as tmux(1) enables you to quickly spit the screen so that you can see the results as you work.

tmux steps automation up to the next level by enabling you to control applications in other panes via keystrokes. This combination can be wired up in any number of ways to create some very interesting auto-responders. Consider the following

watch http headers

With this mechanism in place we can fetch and compare headers using any tool that's capable of printing output or writing to a file—no plugins or specialized functionality required.

Last Updated April 4, 2014
Send questions or comments to ericshane@eradman.com