Amend readmes (#702)

README.md

@@ -4,7 +4,7 @@
 
 Software development often involves running the same commands over and over. Boring!
 
-`watchexec` is a **simple**, standalone tool that watches a path and runs a command whenever it detects modifications.
+`watchexec` is a simple, standalone tool that watches a path and runs a command whenever it detects modifications.
 
 Example use cases:
 
@@ -21,7 +21,7 @@ Example use cases:
 * Coalesces multiple filesystem events into one, for editors that use swap/backup files during saving
 * Loads `.gitignore` and `.ignore` files
 * Uses process groups to keep hold of forking programs
-* Provides the paths that changed in environment variables
+* Provides the paths that changed in environment variables or STDIN
 * Does not require a language runtime, not tied to any particular language or ecosystem
 * [And more!](./crates/cli/#features)
 
@@ -62,11 +62,23 @@ Watchexec pairs well with:
 
 ## Extend
 
-- [watchexec library](./crates/lib/): to create more specialised watchexec-powered tools! such as:
-  - [cargo watch](https://github.com/watchexec/cargo-watch): for Rust/Cargo projects.
+- [watchexec library](./crates/lib/): to create more specialised watchexec-powered tools.
+  - [watchexec-events](./crates/events/): event types for watchexec.
+  - [watchexec-signals](./crates/signals/): signal types for watchexec.
+  - [watchexec-supervisor](./crates/supervisor/): process lifecycle manager (the _exec_ part of watchexec).
 - [clearscreen](https://github.com/watchexec/clearscreen): to clear the (terminal) screen on every platform.
 - [command group](https://github.com/watchexec/command-group): to run commands in process groups.
 - [ignore files](./crates/ignore-files/): to find, parse, and interpret ignore files.
 - [project origins](./crates/project-origins/): to find the origin(s) directory of a project.
 - [notify](https://github.com/notify-rs/notify): to respond to file modifications (third-party).
-- [globset](https://crates.io/crates/globset): to match globs (third-party).
+
+### Downstreams
+
+Selected downstreams of watchexec and associated crates:
+
+- [cargo watch](https://github.com/watchexec/cargo-watch): a specialised watcher for Rust/Cargo projects.
+- [cargo lambda](https://github.com/cargo-lambda/cargo-lambda): a dev tool for Rust-powered AWS Lambda functions.
+- [create-rust-app](https://create-rust-app.dev): a template for Rust+React web apps.
+- [dotter](https://github.com/supercuber/dotter): a dotfile manager.
+- [ghciwatch](https://github.com/mercurytechnologies/ghciwatch): a specialised watcher for Haskell projects.
+- [tectonic](https://tectonic-typesetting.github.io/book/latest/): a TeX/LaTeX typesetting system.

completions/bash

@@ -86,7 +86,7 @@ _watchexec() {
                     return 0
                     ;;
                 --emit-events-to)
-                    COMPREPLY=($(compgen -W "environment stdin file json-stdin json-file none" -- "${cur}"))
+                    COMPREPLY=($(compgen -W "environment stdio file json-stdio json-file none" -- "${cur}"))
                     return 0
                     ;;
                 --env)

completions/fish

@@ -8,7 +8,7 @@ complete -c watchexec -s d -l debounce -d 'Time to wait for new events before ta
 complete -c watchexec -l delay-run -d 'Sleep before running the command' -r
 complete -c watchexec -l poll -d 'Poll for filesystem changes' -r
 complete -c watchexec -l shell -d 'Use a different shell' -r
-complete -c watchexec -l emit-events-to -d 'Configure event emission' -r -f -a "{environment	'',stdin	'',file	'',json-stdin	'',json-file	'',none	''}"
+complete -c watchexec -l emit-events-to -d 'Configure event emission' -r -f -a "{environment	'',stdio	'',file	'',json-stdio	'',json-file	'',none	''}"
 complete -c watchexec -s E -l env -d 'Add env vars to the command' -r
 complete -c watchexec -l color -d 'When to use terminal colours' -r -f -a "{auto	'',always	'',never	''}"
 complete -c watchexec -l project-origin -d 'Set the project origin' -r -f -a "(__fish_complete_directories)"

completions/nu

@@ -9,7 +9,7 @@ module completions {
   }
 
   def "nu-complete watchexec emit_events_to" [] {
-    [ "environment" "stdin" "file" "json-stdin" "json-file" "none" ]
+    [ "environment" "stdio" "file" "json-stdio" "json-file" "none" ]
   }
 
   def "nu-complete watchexec color" [] {

completions/zsh

@@ -30,7 +30,7 @@ _watchexec() {
 '--delay-run=[Sleep before running the command]:DURATION: ' \
 '--poll=[Poll for filesystem changes]' \
 '--shell=[Use a different shell]:SHELL: ' \
-'--emit-events-to=[Configure event emission]:MODE:(environment stdin file json-stdin json-file none)' \
+'--emit-events-to=[Configure event emission]:MODE:(environment stdio file json-stdio json-file none)' \
 '*-E+[Add env vars to the command]:KEY=VALUE: ' \
 '*--env=[Add env vars to the command]:KEY=VALUE: ' \
 '--color=[When to use terminal colours]:MODE:(auto always never)' \

crates/cli/README.md

@@ -45,7 +45,7 @@ Example use cases:
 * Not tied to Git or the presence of a repository/project
 * Does not require a cryptic command line involving `xargs`
 
-## Simple Usage Examples
+## Usage Examples
 
 Watch all JavaScript, CSS and HTML files in the current directory and all subdirectories for changes, running `make` when a change is detected:
 
@@ -65,11 +65,11 @@ Call/restart `python server.py` when any Python file in the current directory (a
 
 Call/restart `my_server` when any file in the current directory (and all subdirectories) changes, sending `SIGKILL` to stop the command:
 
-    $ watchexec -r -s SIGKILL my_server
+    $ watchexec -r --stop-signal SIGKILL my_server
 
 Send a SIGHUP to the command upon changes (Note: using `-n` here we're executing `my_server` directly, instead of wrapping it in a shell:
 
-    $ watchexec -n -s SIGHUP my_server
+    $ watchexec -n --signal SIGHUP my_server
 
 Run `make` when any file changes, using the `.gitignore` file in the current directory to filter:
 
@@ -87,38 +87,40 @@ Run two commands:
 
     $ watchexec 'date; make'
 
+Get desktop ("toast") notifications when the command starts and finishes:
+
+    $ watchexec -N go build
+
+Only run when files are created:
+
+    $ watchexec --fs-events create -- s3 sync . s3://my-bucket
+
 If you come from `entr`, note that the watchexec command is run in a shell by default. You can use `-n` or `--shell=none` to not do that:
 
     $ watchexec -n -- echo ';' lorem ipsum
 
 On Windows, you may prefer to use Powershell:
 
-    $ watchexec --shell=powershell -- test-connection localhost
+    $ watchexec --shell=pwsh -- Test-Connection example.com
 
-## Complex Usage Examples
+You can eschew running commands entirely and get a stream of events to process on your own:
 
-Turn a plain converter tool like PlantUML or Pandoc into a powerful live-editing tool, either as a script
+```console
+$ watchexec --emit-events-to=json-stdio --only-emit-events
 
-    #!/usr/bin/env bash
-    set -Eeuo pipefail
+{"tags":[{"kind":"source","source":"filesystem"},{"kind":"fs","simple":"modify","full":"Modify(Data(Any))"},{"kind":"path","absolute":"/home/code/rust/watchexec/crates/cli/README.md","filetype":"file"}]}
+{"tags":[{"kind":"source","source":"filesystem"},{"kind":"fs","simple":"modify","full":"Modify(Data(Any))"},{"kind":"path","absolute":"/home/code/rust/watchexec/crates/lib/Cargo.toml","filetype":"file"}]}
+{"tags":[{"kind":"source","source":"filesystem"},{"kind":"fs","simple":"modify","full":"Modify(Data(Any))"},{"kind":"path","absolute":"/home/code/rust/watchexec/crates/cli/src/args.rs","filetype":"file"}]}
+```
 
-    SOURCE="test.puml"            # Define source file
-    TARGET="test.png"             # Define conversion target file
-    CONVERT="plantuml $SOURCE"    # Define how to convert source to target
-    VIEW="feh $TARGET"            # Define how to open target file
-    if [ ! -f $TARGET ]; then $CONVERT; fi # Ensure target file exists for opening
-    $VIEW &                                # Open target file in viewer in the background
-    watchexec --filter $SOURCE -- $CONVERT    # Update target file on any source file change
+Print the time commands take to run:
 
-or condensed as a single line
-
-    # Bash
-    $ SOURCE="test.puml"; TARGET="test.png"; CONVERT="plantuml $SOURCE"; VIEW="feh $TARGET"; if [ ! -f $TARGET ]; then $CONVERT; fi; ($VIEW &); watchexec -f $SOURCE -- $CONVERT
-    # Zsh
-    $ SOURCE="test.puml"; TARGET="test.png"; CONVERT="plantuml $SOURCE"; VIEW="feh $TARGET"; if [ ! -f $TARGET ]; then $CONVERT; fi; ($=VIEW &); watchexec -f $SOURCE -- $CONVERT
-
-Replace [PlantUML](https://plantuml.com/) with another converter like [Pandoc](https://pandoc.org/):  `plantuml $SOURCE` turns into `pandoc $SOURCE --output $TARGET`.
-Similarly, replace the [Feh](https://feh.finalrewind.org/) image viewer with another viewer for your target file like the PDF viewer [Evince](https://wiki.gnome.org/Apps/Evince): `feh $TARGET` turns into `evince $TARGET`.
+```console
+$ watchexec --timings -- make
+[Running: make]
+...
+[Command was successful, lasted 52.748081074s]
+```
 
 ## Installation
 
@@ -175,3 +177,5 @@ There's a manual page at `doc/watchexec.1`. Install it to `/usr/share/man/man1/`
 If not bundled, you can generate a manual page with `watchexec --manual > /path/to/watchexec.1`, or view it inline with `watchexec --manual` (requires `man`).
 
 You can also [read a text version](../../doc/watchexec.1.md) or a [PDF](../../doc/watchexec.1.pdf).
+
+Note that it is automatically generated from the help text, so it is not as pretty as a carefully hand-written one.

crates/cli/src/args.rs

@@ -521,7 +521,7 @@ pub struct Args {
 	/// Large numbers of files will either cause the environment to be truncated, or may error or
 	/// crash the process entirely.
 	///
-	/// Two new modes are available: 'stdin' writes absolute paths to the stdin of the command,
+	/// Two new modes are available: 'stdio' writes absolute paths to the stdin of the command,
 	/// one per line, each prefixed with `create:`, `remove:`, `rename:`, `modify:`, or `other:`,
 	/// then closes the handle; 'file' writes the same thing to a temporary file, and its path is
 	/// given with the $WATCHEXEC_EVENTS_FILE environment variable.
@@ -576,7 +576,7 @@ pub struct Args {
 	///       + `code`, the exit, signal, stop, or exception code.
 	///   - `metadata`, additional information about the event.
 	///
-	/// The 'json-stdin' mode will emit JSON events to the standard input of the command, one per
+	/// The 'json-stdio' mode will emit JSON events to the standard input of the command, one per
 	/// line, then close stdin. The 'json-file' mode will create a temporary file, write the
 	/// events to it, and provide the path to the file with the $WATCHEXEC_EVENTS_FILE
 	/// environment variable.
@@ -601,7 +601,7 @@ pub struct Args {
 	/// spawn a new process for each event.
 	///
 	/// This option requires `--emit-events-to` to be set, and restricts the available modes to
-	/// `stdin` and `json-stdin`, modifying their behaviour to write to stdout instead of the stdin
+	/// `stdio` and `json-stdio`, modifying their behaviour to write to stdout instead of the stdin
 	/// of the command.
 	#[arg(
 		long,
@@ -904,9 +904,11 @@ pub struct Args {
 pub enum EmitEvents {
 	#[default]
 	Environment,
-	Stdin,
+	#[value(alias("stdin"))]
+	Stdio,
 	File,
-	JsonStdin,
+	#[value(alias("json-stdin"))]
+	JsonStdio,
 	JsonFile,
 	None,
 }
@@ -1027,12 +1029,12 @@ pub fn get_args() -> Args {
 	if args.only_emit_events
 		&& !matches!(
 			args.emit_events_to,
-			EmitEvents::JsonStdin | EmitEvents::Stdin
+			EmitEvents::JsonStdio | EmitEvents::Stdio
 		) {
 		Args::command()
 			.error(
 				ErrorKind::InvalidValue,
-				"only-emit-events requires --emit-events-to=stdin or --emit-events-to=json-stdin",
+				"only-emit-events requires --emit-events-to=stdio or --emit-events-to=json-stdio",
 			)
 			.exit();
 	}

crates/cli/src/config.rs

@@ -122,13 +122,13 @@ pub fn make_config(args: &Args, state: &State) -> Result<Config> {
 			}
 
 			match emit_events_to {
-				EmitEvents::Stdin => {
+				EmitEvents::Stdio => {
 					println!(
 						"{}",
 						events_to_simple_format(action.events.as_ref()).unwrap_or_default()
 					);
 				}
-				EmitEvents::JsonStdin => {
+				EmitEvents::JsonStdio => {
 					for event in action.events.iter().filter(|e| !e.is_empty()) {
 						println!("{}", serde_json::to_string(event).unwrap_or_default());
 					}
@@ -524,7 +524,7 @@ fn emit_events_to_command(
 		EmitEvents::Environment => {
 			add_envs.extend(emits_to_environment(&events));
 		}
-		EmitEvents::Stdin => match emits_to_file(&emit_file, &events)
+		EmitEvents::Stdio => match emits_to_file(&emit_file, &events)
 			.and_then(|path| File::open(path).into_diagnostic())
 		{
 			Ok(file) => {
@@ -542,7 +542,7 @@ fn emit_events_to_command(
 				error!("Failed to write WATCHEXEC_EVENTS_FILE, continuing without it: {err}");
 			}
 		},
-		EmitEvents::JsonStdin => match emits_to_json_file(&emit_file, &events)
+		EmitEvents::JsonStdio => match emits_to_json_file(&emit_file, &events)
 			.and_then(|path| File::open(path).into_diagnostic())
 		{
 			Ok(file) => {

crates/events/README.md

@@ -16,7 +16,7 @@ Fundamentally, events in watchexec have three purposes:
 3. To carry information about what caused the event, which may be provided to the process.
 
 Outside of Watchexec, this library is particularly useful if you're building a tool that runs under
-it, and want to easily read its events (with `--emit-events-to=json-file` and `--emit-events-to=json-stdin`).
+it, and want to easily read its events (with `--emit-events-to=json-file` and `--emit-events-to=json-stdio`).
 
 ```rust ,no_run
 use std::io::{stdin, Result};

crates/lib/CHANGELOG.md

@@ -11,7 +11,6 @@
 - Watchexec can now supervise multiple commands at once. See [Action](#Action) below, the [Action docs](https://docs.rs/watchexec/latest/watchexec/action/struct.Action.html), and the [Supervisor docs](https://docs.rs/watchexec-supervisor) for more.
 - Because of this new feature, the one where multiple commands could be set under the one supervisor is removed.
 - Watchexec's supervisor was split up into its own crate, [`watchexec-supervisor`](https://docs.rs/watchexec-supervisor).
-- Running as PID1 (e.g. in Docker) is now fully handled, with support from the [`pid1`](https://www.fpcomplete.com/blog/announcing-pid1-crate-for-easier-rust-docker-images/) crate.
 - Tokio requirement is now 1.33.
 - Notify was upgraded to 6.0.
 - Nix was upgraded to 0.27.

doc/watchexec.1

@@ -286,7 +286,7 @@ a process is a very restricted space, while also limited in what it can usefully
 Large numbers of files will either cause the environment to be truncated, or may error or
 crash the process entirely.
 
-Two new modes are available: \*(Aqstdin\*(Aq writes absolute paths to the stdin of the command,
+Two new modes are available: \*(Aqstdio\*(Aq writes absolute paths to the stdin of the command,
 one per line, each prefixed with `create:`, `remove:`, `rename:`, `modify:`, or `other:`,
 then closes the handle; \*(Aqfile\*(Aq writes the same thing to a temporary file, and its path is
 given with the $WATCHEXEC_EVENTS_FILE environment variable.
@@ -341,7 +341,7 @@ The fields are as follows:
       + `code`, the exit, signal, stop, or exception code.
   \- `metadata`, additional information about the event.
 
-The \*(Aqjson\-stdin\*(Aq mode will emit JSON events to the standard input of the command, one per
+The \*(Aqjson\-stdio\*(Aq mode will emit JSON events to the standard input of the command, one per
 line, then close stdin. The \*(Aqjson\-file\*(Aq mode will create a temporary file, write the
 events to it, and provide the path to the file with the $WATCHEXEC_EVENTS_FILE
 environment variable.
@@ -353,7 +353,7 @@ Only emit events to stdout, run no commands.
 
 This is a convenience option for using Watchexec as a file watcher, without running any commands. It is almost equivalent to using `cat` as the command, except that it will not spawn a new process for each event.
 
-This option requires `\-\-emit\-events\-to` to be set, and restricts the available modes to `stdin` and `json\-stdin`, modifying their behaviour to write to stdout instead of the stdin of the command.
+This option requires `\-\-emit\-events\-to` to be set, and restricts the available modes to `stdio` and `json\-stdio`, modifying their behaviour to write to stdout instead of the stdin of the command.
 .TP
 \fB\-E\fR, \fB\-\-env\fR=\fIKEY=VALUE\fR
 Add env vars to the command

doc/watchexec.1.md

@@ -428,7 +428,7 @@ also limited in what it can usefully represent. Large numbers of files
 will either cause the environment to be truncated, or may error or crash
 the process entirely.
 
-Two new modes are available: stdin writes absolute paths to the stdin of
+Two new modes are available: stdio writes absolute paths to the stdin of
 the command, one per line, each prefixed with \`create:\`, \`remove:\`,
 \`rename:\`, \`modify:\`, or \`other:\`, then closes the handle; file
 writes the same thing to a temporary file, and its path is given with
@@ -462,7 +462,7 @@ ends: + \`disposition\`, the exit disposition (success, error, signal,
 stop, exception, continued). + \`code\`, the exit, signal, stop, or
 exception code. - \`metadata\`, additional information about the event.
 
-The json-stdin mode will emit JSON events to the standard input of the
+The json-stdio mode will emit JSON events to the standard input of the
 command, one per line, then close stdin. The json-file mode will create
 a temporary file, write the events to it, and provide the path to the
 file with the \$WATCHEXEC_EVENTS_FILE environment variable.
@@ -479,7 +479,7 @@ as the command, except that it will not spawn a new process for each
 event.
 
 This option requires \`\--emit-events-to\` to be set, and restricts the
-available modes to \`stdin\` and \`json-stdin\`, modifying their
+available modes to \`stdio\` and \`json-stdio\`, modifying their
 behaviour to write to stdout instead of the stdin of the command.
 
 **-E**, **\--env**=*KEY=VALUE*