entr(1)

Run arbitrary commands when files change

overview | download 5.3 | man page

Examples

Rebuild project if sources change

$ ls | entr make

Rebuild project and run tests if the build was successful

$ ls | entr -s 'make && make test'

Restarting Services

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:

$ 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

The restart option starts the utility as a background process that does not have access to STDIN. In this case keyboard input may be provided using a FIFO

$ mkfifo fifo
cat >fifo

Then start the entr in another console

$ ls main.go | entr -r -s '<fifo go run main.go'

Watching for New Files

The directory watch option (-d) was added to react to events when a new file is added to a directory. Since entr relies on standard input piped from other Unix tools, an external shell loop must be used to rescan the file system. One way to implement this feature would be to simply require the users to list directories, but entr will infer the directories if they aren't listed explicitly

$ while true; do
>   ls -d src/*.py | entr -d ./setup.py
> done

Other Implementation Details

Some architectural limitations are for good reasons, but it's not easy to see why a particular restriction applies.

First, the -r flag cannot be used with an interactive task:

1. Closing STDIN on the child allows entr to accept keyboard input.
2. If entr were to close it's own file descriptor to STDIN there is no reliable and immediate way to determine when the child has terminated in order to restore keyboard input.
3. In restart mode signals need to propagate reliably, so we use a new process group. If the utility reads STDIN under this new process group, the kernel will suspend it. Finding your process in the T state is confusing, so we closes STDIN to raise an error instead.

Processing Files

The /_ shortcut for entr was intended as a means of saving typing in the case where you are monitoring one file

$ echo schema.sql | psql -f /_

For any other use it is incorrect because the operating system may consolidate events for files that were changed in close succession, but entr only prints one filename. This approach would also be incomplete because there is no way of detecting changes that occurred if entr isn't running.

Over time I have been asked to extend and enhance the capabilities of the /_ shortcut; this is usually to in an effort to

1. emulate rsync(1) — send only files that changed
2. emulate make(1) — build only files that changed

entr will detect if something changed in your tree, but another tools should handle building source or copying files. Here is an example using a Makefile

  .SUFFIXES: .md .html

  SOURCES != ls input/*.md | awk 'sub("\.md$$", ".html")'

  .md.html:
      markdown2html $< > $@

  all: ${SOURCES}

Then monitor using

while sleep 0.1; do
  ls *.md | entr -d make
done

make uses the modification times of files to determine what needs to be updated. You can also do this comparison in shell, which may be more adaptable to your directory structure

#!/bin/sh

for input in $(ls input/*.md); do
  output="output/$(basename $input .md).html"

  [[ $input -nt $output ]] && {
      (set -x; markdown2html $input > $output)
  }
done

Tuning

The limits page includes instructions for raising the maximum number of watches on BSD, MacOS and Linux.