You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
181 lines
4.7 KiB
181 lines
4.7 KiB
.\"
|
|
.\" Copyright (c) 2012 Eric Radman <ericshane@eradman.com>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.Dd February 18, 2021
|
|
.Dt ENTR 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm entr
|
|
.Nd run arbitrary commands when files change
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl acdnprsz
|
|
.Ar utility
|
|
.Op Ar argument /_ ...
|
|
.Sh DESCRIPTION
|
|
A list of files provided on standard input, and the
|
|
.Ar utility
|
|
is executed using the supplied arguments if any of them change.
|
|
.Nm
|
|
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.
|
|
.Pp
|
|
The arguments are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fl a
|
|
Respond to all events which occur while the
|
|
.Ar utility
|
|
is running.
|
|
Without this option,
|
|
.Nm
|
|
consolidates events in order to avoid looping.
|
|
This option has no effect in conjunction with the
|
|
.Fl r
|
|
flag.
|
|
.It Fl c
|
|
Clear the screen before invoking the
|
|
.Ar utility
|
|
specified on the command line.
|
|
Specify twice to erase the scrollback buffer.
|
|
.It Fl 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.
|
|
Files with names beginning with
|
|
.Ql \&.
|
|
are ignored.
|
|
.It Fl n
|
|
Run in non-interactive mode.
|
|
In this mode
|
|
.Nm entr
|
|
does not attempt to read from the TTY or change its properties.
|
|
.It Fl p
|
|
Postpone the first execution of the
|
|
.Ar utility
|
|
until a file is modified.
|
|
.It Fl r
|
|
Reload a persistent child process.
|
|
As with the standard mode of operation, a
|
|
.Ar utility
|
|
which terminates is not executed again until a file system or keyboard event is
|
|
processed.
|
|
.Dv SIGTERM
|
|
is used to terminate the
|
|
.Ar utility
|
|
before it is restarted.
|
|
A process group is created to prevent shell scripts from masking signals.
|
|
.Nm
|
|
waits for the
|
|
.Ar utility
|
|
to exit to ensure that resources such as sockets have been closed.
|
|
Control of the TTY is not transferred to the child process.
|
|
.It Fl s
|
|
Evaluate the first argument using the interpreter specified by the
|
|
.Ev SHELL
|
|
environment variable.
|
|
If standard output is a TTY, the name of the shell and exit code is printed
|
|
after each invocation.
|
|
.It Fl z
|
|
Exit after the
|
|
.Ar utility
|
|
completes.
|
|
When combined with
|
|
.Fl r
|
|
the
|
|
.Ar utility
|
|
will be restarted again only in response to commands or file system
|
|
events.
|
|
.El
|
|
.Pp
|
|
The first argument named
|
|
.Ar /_
|
|
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
|
|
.Fl s
|
|
option is used, the name of the first file to trigger an event can be read from
|
|
.Va $0 .
|
|
.Sh COMMANDS
|
|
.Nm
|
|
listens for keyboard input and responds to the following commands:
|
|
.Bl -tag -width <space>
|
|
.It Aq Cm space
|
|
Execute the utility immediately.
|
|
If the
|
|
.Fl Cm r
|
|
option is set this will terminate and restart the child process as if a file
|
|
change event had occurred.
|
|
.It Cm q
|
|
Quit; equivalent pressing
|
|
.Aq Cm control-C .
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
If
|
|
.Ev PAGER
|
|
is undefined,
|
|
.Nm
|
|
will assign
|
|
.Pa /bin/cat
|
|
to prevent interactive utilities from waiting for keyboard input if output does
|
|
not fit on the screen.
|
|
.Pp
|
|
If
|
|
.Ev SHELL
|
|
is undefined,
|
|
.Nm entr
|
|
will use
|
|
.Pa /bin/sh .
|
|
.Sh EXIT STATUS
|
|
If the
|
|
.Fl z
|
|
flag is set and the
|
|
.Ar utility
|
|
is successfully executed, the status of the child process is
|
|
returned.
|
|
Otherwise
|
|
.Nm
|
|
normally returns one of the following values:
|
|
.Pp
|
|
.Bl -tag -width Ds -offset indent -compact
|
|
.It 0
|
|
Normal termination after receiving
|
|
.Dv SIGINT
|
|
.It 1
|
|
No regular files were provided as input or an error occurred
|
|
.It 2
|
|
A file was added to a directory and the directory watch option was specified
|
|
.El
|
|
.Sh EXAMPLES
|
|
Rebuild a project if source files change, limiting output to the first 20 lines:
|
|
.Pp
|
|
.Dl $ find src/ | entr -s 'make | sed 20q'
|
|
.Pp
|
|
Launch and auto-reload a node.js server:
|
|
.Pp
|
|
.Dl $ ls *.js | entr -r node app.js
|
|
.Pp
|
|
Clear the screen and run a query after the SQL script is updated:
|
|
.Pp
|
|
.Dl $ echo my.sql | entr -cp psql -f /_
|
|
.Pp
|
|
Rebuild project if a source file is modified or added to the src/ directory:
|
|
.Pp
|
|
.Dl $ while sleep 0.1; do ls src/*.rb | entr -d make; done
|
|
.Pp
|
|
Auto-reload a web server, or terminate if the server exits
|
|
.Pp
|
|
.Dl $ ls * | entr -rz ./httpd
|