Entr: Run arbitrary commands when files change
entr(1)



Run arbitrary commands when files change


overview
|
download 5.6
|
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'


hint:
ag
and
ack
offer many advantages over utilities such as
find(1)
or
ls(1)
in that they recognize files by their contents and are smart enough to
skip directories such as
.git

Status Filters

entr
allows custom status messages to be displayed by writing a
status filters
in
awk(1).
Select a different script by setting the environment variable
ENTR_STATUS_SCRIPT.

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,

immediately start the server
block until any of the listed files change
terminate the background process
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'

Restarting Services with Timeout

In some cases the child process fails to respond when
entr
attempts to restart it. In this case it's helpful to send an
alternate signal or kill the child process if it does not respond.


The
timeout(1)
utility can solve this by sending
SIGKILL
if the utility does not terminate after the specified period

ls app | entr -r timeout -k 5 0 ./app


timeout
can also be used to send an alternate signal, such as
SIGINT

ls app | entr -r timeout -s 2 0 ./app

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:



Closing
STDIN
on the child allows
entr
to accept keyboard input.


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.


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 | entr 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



emulate
rsync(1)
— send only files that changed


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


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.






