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