From 29b6a34d133c6aa530a02281b429578d9bcec6ff Mon Sep 17 00:00:00 2001
From: clawbot <sneak+clawbot@sneak.cloud>
Date: Fri, 2 Oct 2026 03:52:37 +0000
Subject: [PATCH] Name all three forms git describe gives for the version

README, script/version and the version test's header said git describe
gives the tag or the short commit. On a commit after a tag it gives the
tag, the commits since it and the short commit; each place now names
that case too.

Model: opus-5-5
---
 README.md                      | 3 ++-
 script/version                 | 4 +++-
 test/packaging/version.test.ts | 7 ++++---
 3 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 28cb4bf..984fc0f 100644
--- a/README.md
+++ b/README.md
@@ -189,7 +189,8 @@ places, and reads `.gitignore` as its default ignore file — which is why
 - the `VERSION` environment variable, or the `Dockerfile`'s `VERSION` build arg
   (`--build-arg VERSION=...`), when one is given and not empty;
 - otherwise, in a checkout with `.git`, `git describe --tags --always`: the tag
-  on a tagged commit, otherwise the short commit;
+  on a tagged commit; the tag, the commits since it and the short commit on a
+  later commit (`v1.2.3-4-gabc1234`); the short commit when no tag is reachable;
 - otherwise, as in a source tarball, the version `package.json` declares.
 
 The build fails if the checkout has `.git` and the version still comes out
diff --git a/script/version b/script/version
index 92274fc..2af8a6a 100755
--- a/script/version
+++ b/script/version
@@ -7,7 +7,9 @@
 #   1. $VERSION, if set and not empty: an explicit value, such as the
 #      Dockerfile's VERSION build arg.
 #   2. If this checkout has .git, `git describe --tags --always`: the tag
-#      on a tagged commit, otherwise the short commit.
+#      on a tagged commit; the tag, the commits since it and the short
+#      commit on a later commit (v1.2.3-4-gabc1234); the short commit when
+#      no tag is reachable.
 #   3. Otherwise, as in a source tarball, the version package.json declares.
 #
 # A checkout with .git whose version still comes out empty, dev or unknown
diff --git a/test/packaging/version.test.ts b/test/packaging/version.test.ts
index 62a1736..c1395fc 100644
--- a/test/packaging/version.test.ts
+++ b/test/packaging/version.test.ts
@@ -2,9 +2,10 @@
 // `dist/package.json`, which is what `quak --version` reports from a build.
 // A `docker build .` of a clone is given no `VERSION` build arg, so the
 // version has to come from the `.git` in its context: the tag on a tagged
-// commit, otherwise the short commit. A checkout with `.git` that still yields
-// no usable version must fail the build, not ship a version nobody can trace
-// back to its commit.
+// commit; the tag, the commits since it and the short commit on a later commit;
+// the short commit when no tag is reachable. A checkout with `.git` that still
+// yields no usable version must fail the build, not ship a version nobody can
+// trace back to its commit.
 //
 // Each test copies the script into a fresh directory, which the script then
 // treats as the checkout, and executes it there.