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

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

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
+// commit; the tag, the commits since it and the short commit on a later commit;
-// no usable version must fail the build, not ship a version nobody can trace
+// the short commit when no tag is reachable. A checkout with `.git` that still
-// back to its commit.
+// 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.