From 6c633da6ea079b151c2202ddb4bbd7254d8a8b6f Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Fri, 21 Mar 2025 05:21:34 -0400
Subject: [PATCH 1/9] quote() paths in justfile

This makes some recipes work on Windows, and on other systems if
there are wunusual paths, that had previously broken in those
scenarios. That includes the default recipe.
---
 justfile | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/justfile b/justfile
index c1b27f7658c..09f29307c15 100755
--- a/justfile
+++ b/justfile
@@ -3,7 +3,7 @@
 #   like a script, with `./justfile test`, for example.
 
 default:
-    {{ just_executable() }} --list
+    {{ quote(just_executable()) }} --list
 
 alias t := test
 alias c := check
@@ -192,10 +192,10 @@ unit-tests-flaky:
     cargo test -p gix --features async-network-client-async-std
 
 target_dir := `cargo metadata --format-version 1 | jq -r .target_directory`
-ein := target_dir / "debug/ein"
-gix := target_dir / "debug/gix"
-jtt := target_dir / "debug/jtt"
-it := target_dir / "debug/it"
+ein := quote(target_dir / "debug/ein")
+gix := quote(target_dir / "debug/gix")
+jtt := quote(target_dir / "debug/jtt")
+it := quote(target_dir / "debug/it")
 
 # run journey tests (max)
 journey-tests:
@@ -258,7 +258,7 @@ find-yanked:
 # Find shell scripts whose +x/-x bits and magic bytes (e.g. `#!`) disagree
 check-mode:
     cargo build -p internal-tools
-    "{{ it }}" check-mode
+    {{ it }} check-mode
 
 # Delete gix-packetline-blocking/src and regenerate from gix-packetline/src
 copy-packetline:

From 4913663a54db88f251254ad72aeabd6923b82b7c Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Fri, 21 Mar 2025 06:10:54 -0400
Subject: [PATCH 2/9] Use `quote()` instead of concating `'` in `summarize`
 recipe

This is easier to read and verify for correctness, and also more
robust.
---
 justfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/justfile b/justfile
index 09f29307c15..9cbff51d739 100755
--- a/justfile
+++ b/justfile
@@ -243,7 +243,7 @@ audit:
 nextest *FLAGS="--workspace":
     cargo nextest run {{ FLAGS }}
 
-summarize EXPRESSION="all()": (nextest "--workspace --run-ignored all --no-fail-fast --status-level none --final-status-level none -E '" EXPRESSION "'")
+summarize EXPRESSION="all()": (nextest "--workspace --run-ignored all --no-fail-fast --status-level none --final-status-level none -E" quote(EXPRESSION))
 
 # run nightly rustfmt for its extra features, but check that it won't upset stable rustfmt
 fmt:

From 8bec4a28477e8b67aabf873a2e9583631c02b495 Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Fri, 21 Mar 2025 06:14:03 -0400
Subject: [PATCH 3/9] Slightly improve quoting style clarity in justfile

This makes two small changes to the style in which quoting is
expressed in the `justfile`:

- Outside of commands run by a shell (i.e. when `just` interprets
  the quotes), prefer single quotes over double quotes when there
  is both no intent for `\`-escape interpretation to occur and no
  other reason to use `"` (such as a literal `'`).

- Inside commands run by a shel (i.e. when the quoting is shell
  syntax rather than `just` syntax), omit double quotes around a
  few literal arguments that contain no `$` nor other characters
  the shell treats specially. They are alredy omitted in most
  commands similar to these.
---
 justfile | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/justfile b/justfile
index 9cbff51d739..8622e6b06f7 100755
--- a/justfile
+++ b/justfile
@@ -144,7 +144,7 @@ check:
     cargo check --no-default-features --features max-control
 
 # Run cargo doc on all crates
-doc $RUSTDOCFLAGS="-D warnings":
+doc $RUSTDOCFLAGS='-D warnings':
     cargo doc --workspace --no-deps --features need-more-recent-msrv
     cargo doc --features=max,lean,small --workspace --no-deps --features need-more-recent-msrv
 
@@ -158,9 +158,9 @@ unit-tests:
     cargo nextest run -p gix-archive --features tar
     cargo nextest run -p gix-archive --features tar_gz
     cargo nextest run -p gix-archive --features zip
-    cargo nextest run -p gix-status-tests --features "gix-features-parallel"
-    cargo nextest run -p gix-worktree-state-tests --features "gix-features-parallel"
-    cargo nextest run -p gix-worktree-tests --features "gix-features-parallel"
+    cargo nextest run -p gix-status-tests --features gix-features-parallel
+    cargo nextest run -p gix-worktree-state-tests --features gix-features-parallel
+    cargo nextest run -p gix-worktree-tests --features gix-features-parallel
     cd gix-object; \
         set -ex; \
         cargo nextest run; \
@@ -172,10 +172,10 @@ unit-tests:
     cargo nextest run -p gix-odb-tests --features gix-features-parallel
     cargo nextest run -p gix-pack --all-features
     cargo nextest run -p gix-pack-tests --features all-features
-    cargo nextest run -p gix-pack-tests --features "gix-features-parallel"
-    cargo nextest run -p gix-index-tests --features "gix-features-parallel"
+    cargo nextest run -p gix-pack-tests --features gix-features-parallel
+    cargo nextest run -p gix-index-tests --features gix-features-parallel
     cargo nextest run -p gix-packetline --features blocking-io,maybe-async/is_sync --test blocking-packetline
-    cargo nextest run -p gix-packetline --features "async-io" --test async-packetline
+    cargo nextest run -p gix-packetline --features async-io --test async-packetline
     cargo nextest run -p gix-transport --features http-client-curl,maybe-async/is_sync
     cargo nextest run -p gix-transport --features http-client-reqwest,maybe-async/is_sync
     cargo nextest run -p gix-transport --features async-client
@@ -192,10 +192,10 @@ unit-tests-flaky:
     cargo test -p gix --features async-network-client-async-std
 
 target_dir := `cargo metadata --format-version 1 | jq -r .target_directory`
-ein := quote(target_dir / "debug/ein")
-gix := quote(target_dir / "debug/gix")
-jtt := quote(target_dir / "debug/jtt")
-it := quote(target_dir / "debug/it")
+ein := quote(target_dir / 'debug/ein')
+gix := quote(target_dir / 'debug/gix')
+jtt := quote(target_dir / 'debug/jtt')
+it := quote(target_dir / 'debug/it')
 
 # run journey tests (max)
 journey-tests:
@@ -240,10 +240,10 @@ audit:
     cargo deny check advisories bans licenses sources
 
 # run tests with `cargo nextest` (all unit-tests, no doc-tests, faster)
-nextest *FLAGS="--workspace":
+nextest *FLAGS='--workspace':
     cargo nextest run {{ FLAGS }}
 
-summarize EXPRESSION="all()": (nextest "--workspace --run-ignored all --no-fail-fast --status-level none --final-status-level none -E" quote(EXPRESSION))
+summarize EXPRESSION='all()': (nextest '--workspace --run-ignored all --no-fail-fast --status-level none --final-status-level none -E' quote(EXPRESSION))
 
 # run nightly rustfmt for its extra features, but check that it won't upset stable rustfmt
 fmt:

From 47479f1511197150f08b26eaca5f0f2ceb659903 Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Fri, 21 Mar 2025 06:25:15 -0400
Subject: [PATCH 4/9] Refactor `summarize` recipe to be easier to read

Most recipes in `justfile` that use `cargo nextest run` write it
out in a command, even though a `nextest` recipe exists. This is
often done because the command appears in a non-leading line of the
recipe, so having the recipe depend on the `nextest` recipe would
not be feasible. However, it also has the benefit of being more
clear about exactly what command is being run, especially when the
arguments are long and complicated, as in `summarize`.

This changes `summarize` so that it invokes nextest explicitly as a
step of the recipe, rather than depending on `nextest` and passing
its arguments through.
---
 justfile | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/justfile b/justfile
index 8622e6b06f7..aff5336e309 100755
--- a/justfile
+++ b/justfile
@@ -243,7 +243,9 @@ audit:
 nextest *FLAGS='--workspace':
     cargo nextest run {{ FLAGS }}
 
-summarize EXPRESSION='all()': (nextest '--workspace --run-ignored all --no-fail-fast --status-level none --final-status-level none -E' quote(EXPRESSION))
+summarize EXPRESSION='all()':
+    cargo nextest run --workspace --run-ignored all --no-fail-fast \
+        --status-level none --final-status-level none -E {{ quote(EXPRESSION) }}
 
 # run nightly rustfmt for its extra features, but check that it won't upset stable rustfmt
 fmt:

From 892cd329170c8f3a2888c652bc11aa39c20bf91b Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Fri, 21 Mar 2025 07:31:46 -0400
Subject: [PATCH 5/9] Don't use leading `./` when there is another `/`

This changes paths that are excuted by a shell in a `justfile` to
omit the leading `./` when the path already has a `/` later.

A path like `./a` is needed to run `a` from the current directory,
but `./a/b` is just a longer way to express `a/b`, since `a/b`
already has a `/` in it. It is the presence of a `/`, rather than
the presence of a leading `./` specifically, that causes paths to
be looked up relative to the current directory rather than by a
`PATH` search.

The reason to make this change is that a few of the commands that
use those paths are about to get a bit more complicated. It is
hoped that removing this small amount of noise, though currently
inconsequential, will allow the immediately forthcoming change to
be made while preserving readability.
---
 justfile | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/justfile b/justfile
index aff5336e309..6f26be0cfd4 100755
--- a/justfile
+++ b/justfile
@@ -201,29 +201,29 @@ it := quote(target_dir / 'debug/it')
 journey-tests:
     cargo build --features http-client-curl-rustls
     cargo build -p gix-testtools --bin jtt
-    ./tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} max
+    tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} max
 
 # run journey tests (max-pure)
 journey-tests-pure:
     cargo build --no-default-features --features max-pure
     cargo build -p gix-testtools --bin jtt
-    ./tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} max-pure
+    tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} max-pure
 
 # run journey tests (small)
 journey-tests-small:
     cargo build --no-default-features --features small
     cargo build -p gix-testtools
-    ./tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} small
+    tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} small
 
 # run journey tests (lean-async)
 journey-tests-async:
     cargo build --no-default-features --features lean-async
     cargo build -p gix-testtools
-    ./tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} async
+    tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} async
 
 # Run cargo-diet on all crates to see that they are still in bound
 check-size:
-    ./etc/check-package-size.sh
+    etc/check-package-size.sh
 
 # Check the minimal support rust version for currently installed Rust version
 ci-check-msrv:
@@ -264,4 +264,4 @@ check-mode:
 
 # Delete gix-packetline-blocking/src and regenerate from gix-packetline/src
 copy-packetline:
-    ./etc/copy-packetline.sh
+    etc/copy-packetline.sh

From 1db37d17ebaba5b3b118441d2ec1053efd58c0fc Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Fri, 21 Mar 2025 07:02:24 -0400
Subject: [PATCH 6/9] Don't generate cargo metadata eagerly in justfile

- Have the `justfile` wait to run `cargo metadata` until it is
  running a recipe that actually needs the information from it.
  (Currently, that information is always the `target` directory
  location, in whose `debug` subdirectory some binaries are found.)

  This avoids a delay if `cargo metadata` has not run. The length
  of the delay varied but was often noticeable on Windows. Because
  running it again (in the absence of a clean or relevant change)
  is cheap, it is not a performance problem that this runs the
  command multiple times instead of once.

  This also avoids error messages from `cargo metadata` if it can't
  complete, unless it is actually being used. Those messages didn't
  prevent other recipes (besides those that used the metadata) from
  running. But they created the appearance of failure, and also
  were misleading when they didn't come from the recipe being run.

- Handle errors from `cargo metadata` more robustly, by causing
  recipes that actually need the result of `cargo metadata` to fail
  if it fail -- and to fail immediately before attempting any other
  operations -- rather than attempting to use empty data.

  The metadata are piped to `jq -r .target_directory`, which
  actually succeeds even if it doesn't receive any data, giving
  empty output. Before, an attempt was made to use the empty output
  in building paths meant to go to debug builds of some binaries.

  Because the command is now running only when the output is
  actually needed, it is fine to make it hard error when it fails.

  The natural way to do this would be to `set -o pipefail`. But
  while it is in the newest POSIX standard, there remain otherwise
  largely POSIX-compatible `sh` implementations in use that don't
  support it (https://github.com/koalaman/shellcheck/issues/2555).

  Our test suite requires `bash`, so the next obvious choice would
  be to use a shebang recipe or script recipe for `bash`. The
  problem is that shebang and script recipes don't usually work on
  Windows, because `just` passes a Windows path with `\` separators
  to the shell unquoted. This often results in the shell trying to
  run a file whose name is transformed by treating them specially,
  then causing them to dropped as if by quote removal. For example,
  on a recipe named `hello` with a `#!/usr/bin/env bash` shebang:

      /bin/bash: C:UsersekAppDataLocalTempjust-BVbCgphello: No such file or directory

  (One way this happens is by argument processing in `cygwin1.dll`
  or `msys-2.0.dll`, which seek to bridge the gap between the Unix
  expectation that the caller is responsible for all expansions and
  the Windows expectation that the callee is responsible for some.
  See https://github.com/rust-lang/rust/issues/82227. Even when
  only globbing is attempted, `\` can be treated specially if it
  seems to escape a wildcard, or to escape another `\` that seems
  to escape a wildcard, etc.)

  Fortunately, in this case we can just check if the result of
  trying to parse out the `target` directory path gave a nonempty
  result, and treat the failure to do that as a hard error.

- Remove the `check-mode` recipe's need for cargo metadata, by
  having it run the `internal-tools` binary via `cargo run` rather
  than looking up where the `target` directory is and finding `it`
  in `debug` under it.

  That approach is needed for the paths that are passed to the
  journey test runner, but `check-mode` can just use `cargo`.

  The preceding build command could be removed, since `cargo run`
  builds unless the binary is up to date. But keeping them as
  separate commands may make the output more readable.
---
 justfile | 34 +++++++++++++++++++---------------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/justfile b/justfile
index 6f26be0cfd4..a34c5838a4f 100755
--- a/justfile
+++ b/justfile
@@ -2,8 +2,10 @@
 # ^ A shebang isn't required, but allows a justfile to be executed
 #   like a script, with `./justfile test`, for example.
 
+j := quote(just_executable())
+
 default:
-    {{ quote(just_executable()) }} --list
+    {{ j }} --list
 
 alias t := test
 alias c := check
@@ -191,35 +193,37 @@ unit-tests:
 unit-tests-flaky:
     cargo test -p gix --features async-network-client-async-std
 
-target_dir := `cargo metadata --format-version 1 | jq -r .target_directory`
-ein := quote(target_dir / 'debug/ein')
-gix := quote(target_dir / 'debug/gix')
-jtt := quote(target_dir / 'debug/jtt')
-it := quote(target_dir / 'debug/it')
+# depend on this to pre-generate metadata, and/or use it inside a recipe as `"$({{ j }} dbg)"`
+[private]
+dbg:
+    set -eux; \
+        target_dir="$(cargo metadata --format-version 1 | jq -r .target_directory)"; \
+        test -n "$target_dir"; \
+        echo "$target_dir/debug"
 
 # run journey tests (max)
-journey-tests:
+journey-tests: dbg
     cargo build --features http-client-curl-rustls
     cargo build -p gix-testtools --bin jtt
-    tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} max
+    dbg="$({{ j }} dbg)" && tests/journey.sh "$dbg/ein" "$dbg/gix" "$dbg/jtt" max
 
 # run journey tests (max-pure)
-journey-tests-pure:
+journey-tests-pure: dbg
     cargo build --no-default-features --features max-pure
     cargo build -p gix-testtools --bin jtt
-    tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} max-pure
+    dbg="$({{ j }} dbg)" && tests/journey.sh "$dbg/ein" "$dbg/gix" "$dbg/jtt" max-pure
 
 # run journey tests (small)
-journey-tests-small:
+journey-tests-small: dbg
     cargo build --no-default-features --features small
     cargo build -p gix-testtools
-    tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} small
+    dbg="$({{ j }} dbg)" && tests/journey.sh "$dbg/ein" "$dbg/gix" "$dbg/jtt" small
 
 # run journey tests (lean-async)
-journey-tests-async:
+journey-tests-async: dbg
     cargo build --no-default-features --features lean-async
     cargo build -p gix-testtools
-    tests/journey.sh {{ ein }} {{ gix }} {{ jtt }} async
+    dbg="$({{ j }} dbg)" && tests/journey.sh "$dbg/ein" "$dbg/gix" "$dbg/jtt" async
 
 # Run cargo-diet on all crates to see that they are still in bound
 check-size:
@@ -260,7 +264,7 @@ find-yanked:
 # Find shell scripts whose +x/-x bits and magic bytes (e.g. `#!`) disagree
 check-mode:
     cargo build -p internal-tools
-    {{ it }} check-mode
+    cargo run -p internal-tools -- check-mode
 
 # Delete gix-packetline-blocking/src and regenerate from gix-packetline/src
 copy-packetline:

From 4017229db127a9acf38bd5d35d2f5389e03d1f69 Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Fri, 21 Mar 2025 09:13:59 -0400
Subject: [PATCH 7/9] Decrease verbosity on stderr from parsing cargo metadata

---
 justfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/justfile b/justfile
index a34c5838a4f..bb6d294f1f4 100755
--- a/justfile
+++ b/justfile
@@ -196,7 +196,7 @@ unit-tests-flaky:
 # depend on this to pre-generate metadata, and/or use it inside a recipe as `"$({{ j }} dbg)"`
 [private]
 dbg:
-    set -eux; \
+    set -eu; \
         target_dir="$(cargo metadata --format-version 1 | jq -r .target_directory)"; \
         test -n "$target_dir"; \
         echo "$target_dir/debug"

From 151797ff725e2cc6a173a26a2f68ac71aa240f33 Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Fri, 21 Mar 2025 09:14:51 -0400
Subject: [PATCH 8/9] Use the correct `just` for `just --fmt --unstable`

One of the `justfile` recipes ran `just --fmt --unstable`, and did
so as such. The problem with this is that the `just` executable in
the outer `just` call is not guaranteed to be the same `just` that
the inner call in the recipe finds. For example:

- In general, a user might use a `just` that is not in `$PATH` even
  when another `just` is in `$PATH`. This would happen when testing
  changes to `just`, and potentially in other use cases.

- The "inner" `just` is looked up by a POSIX-compatible shell that,
  on Windows, may have a changed environment. For example, the
  `sh.exe` shim provided by Git for Windows modifies environment
  variables including placing some directories in the front of
  `$PATH`. (See discussion in #1864 for details.)

Thus `just` provides a built-in function `just_executable()` that
can be used, and which we already use in the default recipe.

This uses that function instead. However, it is not as simple as
`{{ just_executable() }} --fmt --unstable`, because the path may
require quoting to be run in a shell.

In practice, it almost always needs to be quoted on Windows, where
otherwise a `\` is being given to the shell (which the shell is
required to interpret as a quoting character; this is distinct from
a scenario where a path might be passed as an argument to a shell,
in which case strange things may or may not occur). It might rarely
need to be quoted on other systems too, it it has spaces or other
even weirder contents.

So this uses `{{ quote(just_executable()) }}`. It does so through
the `j` variable that has already been assigned that value.
---
 justfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/justfile b/justfile
index bb6d294f1f4..6c466f133a3 100755
--- a/justfile
+++ b/justfile
@@ -255,7 +255,7 @@ summarize EXPRESSION='all()':
 fmt:
     cargo +nightly fmt --all -- --config-path rustfmt-nightly.toml
     cargo +stable fmt --all -- --check
-    just --fmt --unstable
+    {{ j }} --fmt --unstable
 
 # Cancel this after the first few seconds, as yanked crates will appear in warnings.
 find-yanked:

From fdfceddaba48835791f8517918bef6209e9aa59d Mon Sep 17 00:00:00 2001
From: Eliah Kagan <degeneracypressure@gmail.com>
Date: Fri, 21 Mar 2025 09:56:51 -0400
Subject: [PATCH 9/9] Lightly revise recipe descriptions and add missing ones

- Make the style of `justfile` recipe descriptions more consistent
- Lightly adjust wording and punctuaiton for clarity
- Clarify some to avert misreadings even if a reader is inattentive
- Add descriptions for the several recipes that didn't have them
---
 justfile | 43 +++++++++++++++++++++++--------------------
 1 file changed, 23 insertions(+), 20 deletions(-)

diff --git a/justfile b/justfile
index 6c466f133a3..76d209aa577 100755
--- a/justfile
+++ b/justfile
@@ -4,6 +4,7 @@
 
 j := quote(just_executable())
 
+# List available recipes
 default:
     {{ j }} --list
 
@@ -11,26 +12,27 @@ alias t := test
 alias c := check
 alias nt := nextest
 
-# run all tests, clippy, including journey tests, try building docs
+# Run all tests, clippy, including journey tests, try building docs
 test: clippy check doc unit-tests journey-tests-pure journey-tests-small journey-tests-async journey-tests check-mode
 
-# run all tests, without clippy, and try building docs
+# Run all tests, without clippy, and try building docs
 ci-test: check doc unit-tests check-mode
 
-# run all journey tests - should be run in a fresh clone or after `cargo clean`
+# Run all journey tests - should be run in a fresh clone or after `cargo clean`
 ci-journey-tests: journey-tests-pure journey-tests-small journey-tests-async journey-tests
 
+# Clean the `target` directory
 clear-target:
     cargo clean
 
-# Run cargo clippy on all crates
+# Run `cargo clippy` on all crates
 clippy *clippy-args:
     cargo clippy --workspace --all-targets -- {{ clippy-args }}
     cargo clippy --workspace --no-default-features --features small -- {{ clippy-args }}
     cargo clippy --workspace --no-default-features --features max-pure -- {{ clippy-args }}
     cargo clippy --workspace --no-default-features --features lean-async --tests -- {{ clippy-args }}
 
-# Run cargo clippy on all crates, fixing what can be fixed, and format all code
+# Run `cargo clippy` on all crates, fixing what can be fixed, and format all code
 clippy-fix:
     cargo clippy --fix --workspace --all-targets
     cargo clippy --fix --allow-dirty --workspace --no-default-features --features small
@@ -145,12 +147,12 @@ check:
     cargo check -p gix-odb --features serde
     cargo check --no-default-features --features max-control
 
-# Run cargo doc on all crates
+# Run `cargo doc` on all crates
 doc $RUSTDOCFLAGS='-D warnings':
     cargo doc --workspace --no-deps --features need-more-recent-msrv
     cargo doc --features=max,lean,small --workspace --no-deps --features need-more-recent-msrv
 
-# run all unit tests
+# Run all unit tests
 unit-tests:
     cargo nextest run
     cargo test --doc
@@ -193,7 +195,7 @@ unit-tests:
 unit-tests-flaky:
     cargo test -p gix --features async-network-client-async-std
 
-# depend on this to pre-generate metadata, and/or use it inside a recipe as `"$({{ j }} dbg)"`
+# Depend on this to pre-generate metadata, and/or use it inside a recipe as `"$({{ j }} dbg)"`
 [private]
 dbg:
     set -eu; \
@@ -201,63 +203,64 @@ dbg:
         test -n "$target_dir"; \
         echo "$target_dir/debug"
 
-# run journey tests (max)
+# Run journey tests (`max`)
 journey-tests: dbg
     cargo build --features http-client-curl-rustls
     cargo build -p gix-testtools --bin jtt
     dbg="$({{ j }} dbg)" && tests/journey.sh "$dbg/ein" "$dbg/gix" "$dbg/jtt" max
 
-# run journey tests (max-pure)
+# Run journey tests (`max-pure`)
 journey-tests-pure: dbg
     cargo build --no-default-features --features max-pure
     cargo build -p gix-testtools --bin jtt
     dbg="$({{ j }} dbg)" && tests/journey.sh "$dbg/ein" "$dbg/gix" "$dbg/jtt" max-pure
 
-# run journey tests (small)
+# Run journey tests (`small`)
 journey-tests-small: dbg
     cargo build --no-default-features --features small
     cargo build -p gix-testtools
     dbg="$({{ j }} dbg)" && tests/journey.sh "$dbg/ein" "$dbg/gix" "$dbg/jtt" small
 
-# run journey tests (lean-async)
+# Run journey tests (`lean-async`)
 journey-tests-async: dbg
     cargo build --no-default-features --features lean-async
     cargo build -p gix-testtools
     dbg="$({{ j }} dbg)" && tests/journey.sh "$dbg/ein" "$dbg/gix" "$dbg/jtt" async
 
-# Run cargo-diet on all crates to see that they are still in bound
+# Run `cargo diet` on all crates to see that they are still in bounds
 check-size:
     etc/check-package-size.sh
 
-# Check the minimal support rust version for currently installed Rust version
+# Check the minimal support Rust version, with the currently installed Rust version
 ci-check-msrv:
     rustc --version
     cargo check -p gix
     cargo check -p gix --no-default-features --features async-network-client,max-performance
 
-# Enter a nix-shell able to build on macos
+# Enter a nix-shell able to build on macOS
 nix-shell-macos:
     nix-shell -p pkg-config openssl libiconv darwin.apple_sdk.frameworks.Security darwin.apple_sdk.frameworks.SystemConfiguration
 
-# run various auditing tools to assure we are legal and safe
+# Run various auditing tools to help us stay legal and safe
 audit:
     cargo deny check advisories bans licenses sources
 
-# run tests with `cargo nextest` (all unit-tests, no doc-tests, faster)
+# Run tests with `cargo nextest` (all unit-tests, no doc-tests, faster)
 nextest *FLAGS='--workspace':
     cargo nextest run {{ FLAGS }}
 
+# Run tests with `cargo nextest`, skipping none except as filtered, omitting status reports
 summarize EXPRESSION='all()':
     cargo nextest run --workspace --run-ignored all --no-fail-fast \
         --status-level none --final-status-level none -E {{ quote(EXPRESSION) }}
 
-# run nightly rustfmt for its extra features, but check that it won't upset stable rustfmt
+# Run nightly `rustfmt` for its extra features, but check that it won't upset stable `rustfmt`
 fmt:
     cargo +nightly fmt --all -- --config-path rustfmt-nightly.toml
     cargo +stable fmt --all -- --check
     {{ j }} --fmt --unstable
 
-# Cancel this after the first few seconds, as yanked crates will appear in warnings.
+# Cancel this after the first few seconds, as yanked crates will appear in warnings
 find-yanked:
     cargo install --debug --locked --no-default-features --features max-pure --path .
 
@@ -266,6 +269,6 @@ check-mode:
     cargo build -p internal-tools
     cargo run -p internal-tools -- check-mode
 
-# Delete gix-packetline-blocking/src and regenerate from gix-packetline/src
+# Delete `gix-packetline-blocking/src` and regenerate from `gix-packetline/src`
 copy-packetline:
     etc/copy-packetline.sh