From 9f0c6b3ca30cf4154e58de8ba72c9fa3b11431f7 Mon Sep 17 00:00:00 2001 From: Nils Lehnen <30603423+iderex@users.noreply.github.com> Date: Fri, 21 Aug 2026 16:02:12 +0200 Subject: [PATCH] Restore the operator-guide pastes that reproduce (#155) This does not finish #155. Two more of the path groups that commit removed are still missing. What was wrong. `d3edfc95b8526033c79cb26afe48282c2c090e32` took its tree from an older state of the default branch and landed on top of a newer one, under a message describing a change to how one workflow pin is commented. `docs/operator-guide.md` was among the seven paths it replaced, and it is the only commit to have touched that file since, so the file went back to a form whose two pastes had already been repaired. Both are back to the repaired form, and the repair is a rule-one repair rather than a preference. The exit-code paragraph quoted a `git grep -n`, and the line number in that paste is now wrong while the claim it supports is still true: git grep -n 'ExitAskedAndDeliveredNothing = ' -- internal/hardware internal/hardware/hardware.go:54:const ExitAskedAndDeliveredNothing = 3 The document on the default branch pastes that same command with `45`. Nothing about the constant changed; an edit above it moved the line, which is exactly what the removed paragraph says happens and why the command it restores carries no `-n`: git grep 'ExitAskedAndDeliveredNothing = ' -- internal/hardware internal/hardware/hardware.go:const ExitAskedAndDeliveredNothing = 3 The unknown-verb example is the second. It had been cut off after the one error line, and the runner prints the help text after it: go run ./cmd/lab frobnicate lab: unknown verb "frobnicate" lab reads this repository and reports what it examined. ... exit status 2 The restored line describes that text rather than pasting it, for the reason the restored paragraph gives: a copy of the help text in this document drifts against the runner that prints it, and the runner is what a reader is checking. What failure this prevents is an operator reading a quotation that no longer reproduces and concluding the tree, rather than the document, has moved. The blob is the bytes that were there rather than a retyping of them: git rev-parse 90656ba:docs/operator-guide.md 6775f1473b6af20969eb75003d6bc96854e0aca7 git hash-object docs/operator-guide.md 6775f1473b6af20969eb75003d6bc96854e0aca7 Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com> --- docs/operator-guide.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/operator-guide.md b/docs/operator-guide.md index dc5acd9..6775f14 100644 --- a/docs/operator-guide.md +++ b/docs/operator-guide.md @@ -148,16 +148,27 @@ anything in the tree. Three ways to reach it, each printing to standard error: ./lab frobnicate lab: unknown verb "frobnicate" + (and then the help text, because the verb is not one it has) ./lab (the help text, because no verb was given) +The help text is described rather than pasted in both of those, because a copy +of it here drifts against the runner that prints it, and the runner is the +thing a reader is checking. + `3` is not a code this command returns. It belongs to the integration-hardware harness under `internal/hardware`, which is asked for separately, and it is declared where its only producer is: - git grep -n 'ExitAskedAndDeliveredNothing = ' -- internal/hardware - internal/hardware/hardware.go:45:const ExitAskedAndDeliveredNothing = 3 + git grep 'ExitAskedAndDeliveredNothing = ' -- internal/hardware + internal/hardware/hardware.go:const ExitAskedAndDeliveredNothing = 3 + +That command carries no line number on purpose. With `-n` the paste names a +line rather than a declaration, and an edit anywhere above the constant moves +the line without changing anything the sentence claims, so the quotation goes +stale while the claim it supports stays true. The file and the declaration are +what the claim rests on and neither of them moves. So the record fixes four codes, `lab` returns three of them, and a caller keyed on any of the four is reading that record whether or not anybody said so.