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

Debian                                          February 6, 2025                                         ENTR(1)