NAME
entr
—
run arbitrary commands when files
change
SYNOPSIS
entr |
[-acdnprsxz ] utility
[argument /_ ...] |
DESCRIPTION
A list of files provided on standard input, and the
utility is executed using the supplied arguments if
any of them change. entr
waits for the child process
to finish before responding to subsequent file system events. A TTY is also
opened before entering the watch loop in order to support interactive
utilities.
The arguments are as follows:
-a
- Respond to all events which occur while the utility
is running. Without this option,
entr
consolidates events in order to avoid looping. This option has no effect in conjunction with the-r
flag. -c
- Clear the screen before invoking the utility specified on the command line. Specify twice to erase the scrollback buffer.
-d
- Track the directories of regular files provided as input and exit if a new
file is added. This option also enables directories to be specified
explicitly. If specified twice, all new entries to a directory are
recognized, otherwise files with names beginning with
‘
.
’ are ignored. -n
- Run in non-interactive mode. In this mode
entr
does not attempt to read from the TTY or change its properties. -p
- Postpone the first execution of the utility until a file is modified.
-r
- Reload a persistent child process. As with the standard mode of operation,
a utility which terminates is not executed again
until a file system or keyboard event is processed.
SIGTERM
is used to terminate the utility before it is restarted. A process group is created to prevent shell scripts from masking signals.entr
waits for the utility to exit to ensure that resources such as sockets have been closed. Control of the TTY is not transferred to the child process. -s
- Evaluate the first argument using the interpreter specified by the
SHELL
environment variable. -x
- Format custom exit status messages using a persistent
awk(1) process. The path to the status script is defined by
the environment variable
ENTR_STATUS_SCRIPT
. If the status script does not exist,entr
will create an example. Shell commands and file redirection is not permitted by default, but may be enabled by specifying-x
twice. -z
- Exit after the utility completes. When combined with
-r
the utility will be restarted again only in response to commands or file system events.
The first argument named /_ is replaced with
the absolute path of the first file to trigger an event. The first file
under watch is used as the default. If the -s
option
is used, the name of the first file to trigger an event can be read from
$0.
COMMANDS
entr
listens for keyboard input and
responds to the following commands:
- ⟨
space
⟩ - Execute the utility immediately. If the
-
r
option is set this will terminate and restart the child process as if a file change event had occurred. q
- Quit; equivalent pressing
⟨
control-C
⟩.
ENVIRONMENT
ENTR_STATUS_SCRIPT
- The path to the exit status script enabled by the
-x
option. By default $HOME/.entr/status.awk is evaluated. PAGER
- Set to /bin/cat by default to prevent interactive utilities from waiting for keyboard input if output does not fit on the screen.
SHELL
- Specify the shell to use with the
-s
flag. The default is /bin/sh. EV_TRACE
- Print file system event messages.
EXIT STATUS
If the -z
flag is set and the
utility is successfully executed, the status of the
child process is returned. If the child process was terminated by a signal,
the exit status is the signal number plus 128.
entr
normally returns one of the following
values:
- 0
- Normal termination after receiving
SIGINT
- 1
- No regular files were provided as input or an error occurred
- 2
- A file was added to a directory and the directory watch option was specified
EXAMPLES
Rebuild a project if source files change, limiting output to the first 20 lines:
$ find src/ | entr -s 'make | head -n
20'
Launch and auto-reload a node.js server:
$ ls *.js | entr -r node
app.js
Clear the screen and run a query after the SQL script is updated:
$ echo my.sql | entr -cp psql -f
/_
Rebuild project if a source file is modified or added to the src/ directory:
$ while sleep 0.1; do ls src/*.rb |
entr -d make; done
Auto-reload a web server, or terminate if the server exits
$ ls * | entr -rz
./httpd