Docs for CARGO_TERM_COLOR etc

NEWS.md

@@ -1,6 +1,7 @@
 # cargo-mutants changelog
 
 ## Unreleased
+
 ## 24.1.2
 
 - New: `--in-place` option tests mutations in the original source tree, without copying the tree. This is faster and uses less disk space, but it's incompatible with `--jobs`, and you must be careful not to edit or commit the source tree while tests are running.

book/src/SUMMARY.md

@@ -12,6 +12,7 @@
   - [Filtering files](skip_files.md)
   - [Filtering functions and mutants](filter_mutants.md)
 - [Controlling cargo-mutants](controlling.md)
+  - [Display and output](output.md)
   - [Listing and previewing mutations](list.md)
   - [Workspaces and packages](workspaces.md)
   - [Passing options to Cargo](cargo-args.md)

book/src/ci.md

@@ -23,6 +23,9 @@ Here is an example of a GitHub Actions workflow that runs mutation tests and upl
 ```yml
 name: cargo-mutants
 
+env:
+  CARGO_TERM_COLOR: always
+
 on:
   push:
     branches:

book/src/controlling.md

@@ -26,14 +26,4 @@ the source.
 `-d`, `--dir`: Test the Rust tree in the given directory, rather than the source tree
 enclosing the working directory where cargo-mutants is launched.
 
-## Console output
-
-`-v`, `--caught`: Also print mutants that were caught by tests.
-
-`-V`, `--unviable`: Also print mutants that failed `cargo build`.
-
-`--no-times`: Don't print elapsed times.
-
-`-L`, `--level`, and `$CARGO_MUTANTS_TRACE_LEVEL`: set the verbosity of trace
-output to stdout. The default is `info`, and it can be increased to `debug` or
-`trace`.
+`--manifest-path`: Also selects the tree to test, but takes a path to a Cargo.toml file rather than a directory. (This is less convenient but compatible with other Cargo commands.)

book/src/output.md

@@ -0,0 +1,23 @@
+# Display and output
+
+cargo-mutants writes a list of missed or timed-out mutants to stderr, and optionally mutants that were caught (with `--caught`) or failed to build (with `--unviable`) to stdout. It writes error or debug messages to stderr.
+
+The following options control what is printed to stdout and stderr.
+
+`-v`, `--caught`: Also print mutants that were caught by tests.
+
+`-V`, `--unviable`: Also print mutants that failed `cargo build`.
+
+`--no-times`: Don't print elapsed times. (This is intended mostly to make the output more stable for testing.)
+
+## Colors
+
+`--colors=always|never|auto`: Control whether to use colors in output. The default is `auto`, which will write colors if the output is a terminal that supports colors. Color support is detected independently for stdout and stderr, so you should still see colors on stderr if stdout is redirected.
+
+The same values can be set with the `CARGO_TERM_COLOR` environment variable, which is respected by many Cargo commands.
+
+cargo-mutants also respects the [`NO_COLOR`](https://no-color.org/) and [`CLICOLOR_FORCE`](https://bixense.com/clicolors/) environment variables. If they are set to a value other than `0` then colors will be disabled or enabled regardless of any other settings.
+
+## Debug trace
+
+`-L`, `--level`, and `$CARGO_MUTANTS_TRACE_LEVEL`: set the verbosity of trace output to stderr. The default is `info`, and it can be increased to `debug` or `trace`.

book/src/pr-diff.md

@@ -10,6 +10,9 @@ name: Tests
 permissions:
   contents: read
 
+env:
+  CARGO_TERM_COLOR: always
+
 on:
   push:
     branches: