Rewrite TODO.md sentence by sentence (closes #135)

TODO.md is the project's own task list, judged by the same rules as
README.md: short sentences, lists as bullets, nothing a newcomer reads
twice. Every completed step is kept with its date and its issue or
branch, and every fact the old entries recorded is kept too, in short
sentences. The 2026-07-22 policy-compliance checklist is folded into
the step that did the work, and the accepted divergence from the
layout policy gets a section of its own. Workflow, Status and Next
Step keep their rules unchanged.

Model: fable-5-1

Dockerfile

@@ -1,16 +1,23 @@
-# Every stage declares ARG CACHEBUST first: script/ passes a new value
-# on every build, which reruns every RUN step after it. The steps that
-# compile mount Go's build cache, which survives from build to build.
+# In every stage ARG CACHEBUST comes right after the steps that install
+# system packages and download Go's modules, or right after FROM in a
+# stage with neither, and every step that lints, tests or compiles
+# comes after it. script/ passes a new value on every build, which
+# reruns every RUN step after it. Docker keeps the layers above it
+# until the base image, their own lines or go.mod and go.sum change.
+# The steps that compile mount Go's build cache, and golangci-lint run
+# also mounts golangci-lint's; both survive from build to build. The
+# test phase runs as nobody and so mounts Go's build cache at
+# /tmp/.cache/go-build; its own comment says why.
 
 # Lint phase, built alone by script/lint. The tools are invoked directly
 # rather than through `make lint`, which runs docker itself and so cannot
 # run inside a build step.
 # golangci/golangci-lint:v2.14.0, 2026-10-07
 FROM golangci/golangci-lint@sha256:ad862ba6b3798cbe0fd9fd7408d498fd74fbd2623a92406b2fd3898faf0bf98f AS lint
-ARG CACHEBUST
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
+ARG CACHEBUST
 COPY . .
 
 # The gofmt half of `make fmt-check`. gofmt's output is assigned to a
@@ -24,6 +31,7 @@ RUN files="$(gofmt -s -l .)" && \
 # Validates .golangci.yml against the schema the pinned binary embeds.
 RUN golangci-lint config verify --config .golangci.yml
 RUN --mount=type=cache,target=/root/.cache/go-build \
+    --mount=type=cache,target=/root/.cache/golangci-lint \
     golangci-lint run --config .golangci.yml ./...
 
 # Test phase, built alone by script/test. -race needs cgo and so a C
@@ -38,12 +46,12 @@ RUN --mount=type=cache,target=/root/.cache/go-build \
 # nobody (65534) so the tests can write to it.
 # golang:1.25-trixie, 2026-10-04
 FROM golang@sha256:2c4c60ef415fbfa5e90300722293bef36c5e63fae17570ce18f580af933dbd73 AS test
-ARG CACHEBUST
 USER nobody
 ENV HOME=/tmp
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
+ARG CACHEBUST
 COPY . .
 RUN --mount=type=cache,target=/tmp/.cache/go-build,uid=65534,gid=65534 \
     go test -count=1 -timeout 90s -race -cover ./... || \
@@ -51,19 +59,19 @@ RUN --mount=type=cache,target=/tmp/.cache/go-build,uid=65534,gid=65534 \
       go test -count=1 -timeout 90s -race -v ./...; exit 1; }
 
 # Build stage. Nothing is wanted from either phase above; the copies are
-# what make BuildKit build them first, so this stage cannot run unless
-# lint and test passed.
+# what make BuildKit build them first, so nothing after them can run
+# unless lint and test passed.
 # golang:1.25-alpine, 2026-07-23
 FROM golang@sha256:56961d79ea8129efddcc0b8643fd8a5416b4e6228cfd477e3fd61deb2672c587 AS builder
-ARG CACHEBUST
-COPY --from=lint /src/go.sum /dev/null
-COPY --from=test /src/go.sum /dev/null
 RUN apk add --no-cache git make
-# A tar-stream context keeps the sender's file owners, which git refuses.
-RUN git config --system --add safe.directory /src
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
+ARG CACHEBUST
+COPY --from=lint /src/go.sum /dev/null
+COPY --from=test /src/go.sum /dev/null
+# A tar-stream context keeps the sender's file owners, which git refuses.
+RUN git config --system --add safe.directory /src
 COPY . .
 
 # The version stamped into the binary: the VERSION build argument when

README.md

@@ -3,22 +3,22 @@
 ## Description
 
 `sfdupes` is an MIT-licensed Go CLI tool by [@sneak](https://sneak.berlin) that
-quickly identifies _candidate_ duplicate files — and, ultimately, entire
-duplicate directory trees — across very large filesystems without reading every
-byte of every file. Files are considered duplicates when their sizes are equal
-and they agree on a short ladder of hashes. A file under 10 MiB is hashed in
-full and compared directly. A larger file is gated first on the SHA-256 of its
-first 64 KiB and of its last 64 KiB, and only when its size and both of those
-match another file's is it read for a content hash to compare — the SHA-256 of
-the whole file when it is under 50 MiB, or of gigabyte-spaced 1 MiB samples when
-it is 50 MiB or larger. Below 50 MiB the content hash is proof of identical
-content; at or above 50 MiB it is a strong candidate signal rather than proof,
-because the gaps between samples are never read. The intended use is finding
-duplicate downloads and duplicated directory trees on multi-terabyte ZFS servers
-where reading every byte of every file is prohibitively expensive. `scan`
-maintains a persistent SQLite database of file signatures that survives between
-runs, so it can be run from cron and the reports can be generated at any time
-from the most recent scan.
+quickly finds _candidate_ duplicate files, and ultimately whole duplicate
+directory trees, on very large filesystems. It does this without reading every
+byte of every file.
+
+Two files are duplicates when they have the same size and the same three SHA-256
+hashes. Two of the hashes cover the first and the last 64 KiB of the file. The
+third, the content hash, covers the whole file when it is under 100 MiB, so a
+match proves identical content. At 100 MiB and above it covers only 1 MiB at
+each gigabyte, so such a file is never read in full. A match there is a strong
+candidate rather than proof.
+
+The intended use is finding duplicate downloads and duplicated directory trees
+on multi-terabyte ZFS servers, where reading every byte of every file is
+prohibitively expensive. `scan` keeps a persistent SQLite database of file
+signatures between runs, so it can run from cron. The reports can be generated
+at any time from the most recent scan.
 
 This README is the complete and authoritative specification.
 
@@ -34,13 +34,13 @@ export SFDUPES_DATABASE="$HOME/.local/share/sfdupes/db.sqlite"
 
 `scan` walks one or more filesystem trees and maintains one database record per
 regular file (path, size, mtime, head hash, tail hash, content hash). The
-database persists between runs; a rescan only hashes files that are new or
-changed, or that may have gained a duplicate since the last scan, and removes
-records for files that no longer exist. `report` reads the database and prints
-the file-level duplicates report. `trees` reads the same database and prints the
-duplicate-tree report. `info` prints the database's details: its path, the sizes
-of its files and the number of its records. A missing/invalid subcommand — or a
-`scan` invocation with no `PATH` operand — prints a usage message and exits 2.
+database persists between runs. A rescan hashes only the files that are new or
+changed, and removes the records of files that no longer exist. `report` reads
+the database and prints the file-level duplicates report. `trees` reads the same
+database and prints the duplicate-tree report. `info` prints the database's
+details: its path, the sizes of its files and the number of its records. A
+missing/invalid subcommand — or a `scan` invocation with no `PATH` operand —
+prints a usage message and exits 2.
 
 The database defaults to `/var/lib/sfdupes/db.sqlite` and can be placed anywhere
 by setting `SFDUPES_DATABASE`. The intended deployment is a daily `sfdupes scan`
@@ -49,15 +49,40 @@ results are as fresh as the last completed scan.
 
 ### Install
 
-With Go installed, this builds and installs the current `main` branch:
+With Go installed, this builds and installs the newest release:
+
+```sh
+go install sneak.berlin/go/sfdupes@latest
+```
+
+Until 1.0, releases are `v0.0.N` tags on the tip of the `main` branch: each time
+`main` moves and its tip passes `script/cibuild`, that tip is tagged with the
+next `v0.0.N`. So `@latest` installs `main`'s tip once it has passed the build.
+`@main` installs the tip before it is tagged:
 
 ```sh
 go install sneak.berlin/go/sfdupes@main
 ```
 
-The binary goes to `$(go env GOPATH)/bin`, or to `$GOBIN` when that is set. A
-binary installed this way reports its version as `dev`; one built from a clone
-or into the Docker image carries the git tag or commit it was built from.
+`v0.0.1` is an early build without a database. It does not work as this README
+describes, and `go.mod` retracts it.
+
+The binary goes to `$(go env GOPATH)/bin`, or to `$GOBIN` when that is set. To
+see which version an installed binary is:
+
+```sh
+sfdupes --version
+go version -m "$(command -v sfdupes)"
+```
+
+`sfdupes --version` prints `sfdupes VERSION`. For a binary from `go install`,
+`VERSION` is the version Go recorded in it: the release tag, such as `v0.0.3`,
+or for `@main` a pseudo-version ending in the first 12 characters of the
+commit's hash. A binary built from a clone or into the Docker image carries the
+git tag or commit it was built from instead, and `VERSION` is `dev` only when
+the binary carries no version at all. `go version -m` prints what Go recorded in
+the binary; its `mod` line names the module's version. Binaries from `v0.0.2`
+and earlier print `dev`, so check those with `go version -m`.
 
 From a clone, `make build` writes the binary to `./sfdupes`:
 
@@ -97,12 +122,19 @@ As a file `/etc/cron.d/sfdupes`:
   the first scan. To keep it elsewhere, set
   `SFDUPES_DATABASE=/path/to/db.sqlite` before the command on the same line.
 - `scan` writes nothing to stdout. Its stderr, appended here to
-  `/var/log/sfdupes.log`, holds a first line naming the database (see
-  "Database"), plain progress lines naming each phase and its place among the
-  five, as `[2/5] walk` (one as the phase starts, one every 5 seconds while it
-  runs, and one as it ends), a warning for each path it skips, and the summary
-  line (see "Progress" and "`scan` mode"). The log grows with every scan; rotate
-  it like any other.
+  `/var/log/sfdupes.log`, holds these lines:
+    - a first line naming the database (see "Database");
+    - plain progress lines naming each phase and its place among the four, as
+      `[2/4] walk`: one as the phase starts, one every 5 seconds while it runs,
+      and one as it ends;
+    - a warning for each path it skips;
+    - a line for each default exclude its walk does not enter, and for each path
+      it leaves out because it is not on a persistent filesystem (see "Rules for
+      the walk");
+    - the summary line (see "Progress" and "`scan` mode").
+
+    The log grows with every scan; rotate it like any other.
+
 - Skipped paths do not fail a scan: it still exits 0, and cron sends nothing. A
   scan that fails, or is stopped by `SIGINT` or `SIGTERM`, exits 1 with the
   reason among the last lines of the log; `tail` prints them, and cron mails
@@ -126,7 +158,7 @@ A row is a candidate, not proof:
 
 - The reports read only the database, so they show the files as of the last
   scan; a file may have changed or gone since.
-- A file of 50 MiB or more is compared only on samples of its content (see
+- A file of 100 MiB or more is compared only on samples of its content (see
   "Duplicate detection").
 - Paths that are hard links to one file are listed as duplicates, but they share
   their data, so removing one frees nothing.
@@ -161,22 +193,23 @@ or a symlink, which `trees` does not see.
 
 ## Rationale
 
-Duplicate finders that hash entire files do not scale to the target environment:
-~10 million files and ~150 TB on possibly slow or busy disks (a ZFS pool under
-resilver). sfdupes spends disk I/O only on files whose size at least one other
-file shares, since a size-unique file cannot be a duplicate. Of those, a file
-under 10 MiB is read in full; a larger one has its cheap end windows read first,
-and is read for a content hash only when its size and both end windows match
-another file's — the whole file below 50 MiB, but only gigabyte-spaced samples
-at or above 50 MiB, so the largest files are never read in full. This keeps a
-full-filesystem sweep tractable, and the signatures are kept in a persistent
-database, so the expensive filesystem pass is incremental: a rescan re-hashes
-only files whose recorded mtime or size changed, plus — for its content hash — a
-file of 10 MiB or more whose size and end windows have come to match another
-file's. All analysis happens offline from the database alone. The end goal is
-not individual files but whole duplicated trees — duplicate extractions,
-duplicate downloads, copied project trees — which an operator can consider
-removing as a unit.
+Duplicate finders that hash every file in full do not scale to the target
+environment. It holds about 10 million files and 150 TB, on disks that may be
+slow or busy, such as a ZFS pool under resilver.
+
+sfdupes reads a file under 100 MiB in full, and a larger one only at its two
+ends and at 1 MiB per gigabyte. A full read of a small file is cheap, and it
+makes the comparison exact. A full read of every large file would take
+unreasonably long. Sampling cuts a 150 GiB file to about 150 MiB of reads, at
+the price of a comparison that is not exact.
+
+The hashes are kept in a persistent database, so the expensive filesystem pass
+is incremental. A rescan reads only the files that are new or whose size or
+mtime changed. All analysis then works from the database alone.
+
+The end goal is not individual files but whole duplicated trees, such as a
+download extracted twice. An operator can consider removing such a tree as a
+unit.
 
 ## Design
 
@@ -188,14 +221,10 @@ Goals, in order:
     trees), so the operator can consider removing an entire subtree at once.
     File-level duplicate detection is the foundation; tree-level detection is
     built on top of it.
-2.  **Spend I/O in proportion to duplicate likelihood.** Only files whose size
-    at least one other file shares are read at all — a size-unique file cannot
-    be a duplicate. Those are compared by the ladder in "Duplicate detection"
-    below: a file under 10 MiB is hashed in full, while a larger file is gated
-    on cheap 64 KiB end windows first, and gets a content hash only when its
-    size and both end windows match another file's. That hash reads the whole
-    file below 50 MiB but only gigabyte-spaced 1 MiB samples at or above it, so
-    the very largest files are still never read in full. Scale target: tens of
+2.  **Bound the I/O per file.** A file is read only when it is new or has
+    changed. A file under 100 MiB is then read in full, and a larger one only at
+    its ends and at 1 MiB per gigabyte (see "Duplicate detection" below).
+    Therefore no file of 100 MiB or more is read in full. Scale target: tens of
     millions of files, ~150 TB filesystem, possibly slow or busy disks (ZFS pool
     under resilver). Holding one small record (path, size, mtime) per file in
     memory during a scan is acceptable; holding every file's hashes is not (they
@@ -208,12 +237,10 @@ Goals, in order:
     being read, so its memory grows with the number of directories and with the
     size of the largest directory.
 3.  **Scan incrementally, analyze offline.** The expensive filesystem scan
-    maintains a persistent database; an unchanged file is never read again on a
-    rescan, except to compute its content hash once a file of 10 MiB or more
-    comes to match another on size and both end windows. All analysis (`report`,
-    `trees`) works from the database alone and must never touch the scanned
-    filesystem again. `scan` is designed to be cronned; the reports run at any
-    time against the last completed scan.
+    maintains a persistent database, and an unchanged file is never read again
+    on a rescan. All analysis (`report`, `trees`) works from the database alone
+    and must never touch the scanned filesystem again. `scan` is designed to be
+    cronned; the reports run at any time against the last completed scan.
 4.  **Clean stream separation.** Everything on stdout is machine-readable data.
     All progress, warnings, summaries, and help and usage text go to stderr.
     Never mix them.
@@ -245,10 +272,10 @@ Four subcommands, all implemented:
     from the database records, compute a Merkle-style digest per directory, and
     report maximal groups of identical trees.
 4.  `info` — the database's details: its path, the sizes of its files, its
-    schema version and the counts of its records.
+    schema version, the number of its records and their total size.
 
 ```
-sfdupes scan [--workers N] [-x] PATH...
+sfdupes scan [--workers N] [-x] [--no-default-excludes] PATH...
 sfdupes report > dupes.tsv
 sfdupes trees > dupetrees.tsv
 sfdupes info
@@ -257,12 +284,13 @@ sfdupes [command] --help
 ```
 
 `--workers N` sets the size of each `scan` worker pool (default: the number of
-CPUs), and `-x` (`--one-file-system`) keeps the walk of each operand on that
-operand's filesystem; both are described under "`scan` mode".
-`sfdupes --version` (or `-v`) prints one line, `sfdupes VERSION`, to stdout and
-exits 0, writing nothing to stderr. `-h` or `--help`, alone or after a
-subcommand, prints the help text to stderr and exits 0, writing nothing to
-stdout.
+CPUs), `-x` (`--one-file-system`) keeps the walk of each operand on that
+operand's filesystem, and `--no-default-excludes` lets the walk enter the
+default excludes, a list of paths; all three are described under "`scan` mode".
+`sfdupes --version` (or `-v`) prints one line, `sfdupes VERSION` (see
+"Install"), to stdout and exits 0, writing nothing to stderr. `-h` or `--help`,
+alone or after a subcommand, prints the help text to stderr and exits 0, writing
+nothing to stdout.
 
 ### Database
 
@@ -340,9 +368,7 @@ All four subcommands operate on a single SQLite database file:
     - While it loads the existing records (`load`) and walks: no records. A
       first scan's database holds none, however long its walk has run.
     - During the hash phase: the first records, committed 10,000 at a time.
-    - In the update phase: the rest of the hashed records, the records for
-      size-unique files, and the deletions.
-    - In the content phase: content hashes, again committed 10,000 at a time.
+    - In the update phase: the rest of the hashed records, and the deletions.
     - At the end, as it closes the database: the `-wal` and `-shm` files go
       away, unless a report still has the database open (see above).
 - `report`, `trees` and `info` open the database read-only and need only read
@@ -362,9 +388,9 @@ All four subcommands operate on a single SQLite database file:
         size       INTEGER NOT NULL,  -- bytes, from lstat
         mtime      INTEGER NOT NULL,  -- whole Unix seconds of the mtime, from lstat
         mtime_nsec INTEGER NOT NULL,  -- nanoseconds within that second, 0 to 999999999
-        head       TEXT NOT NULL,     -- lowercase-hex SHA-256; first 64 KiB, or whole file under 10 MiB
-        tail       TEXT NOT NULL,     -- lowercase-hex SHA-256; last 64 KiB, or whole file under 10 MiB
-        content    TEXT NOT NULL      -- lowercase-hex SHA-256, whole file or samples
+        head       BLOB NOT NULL,     -- raw 32-byte SHA-256 of the first 64 KiB
+        tail       BLOB NOT NULL,     -- raw 32-byte SHA-256 of the last 64 KiB
+        content    BLOB NOT NULL      -- raw 32-byte SHA-256; whole file under 100 MiB, else samples
     ) WITHOUT ROWID;
     CREATE INDEX files_signature ON files (size, head, tail, content);
     ```
@@ -375,57 +401,46 @@ All four subcommands operate on a single SQLite database file:
     nanoseconds past that second. Split this way they hold any mtime a
     filesystem can record, one before 1678 or after 2262 included, which a
     single 64-bit count of nanoseconds cannot. They are used only for change
-    detection and are not part of the duplicate key. For a file under 10 MiB
-    `head`, `tail`, and `content` all hold the whole-file hash (that range is
-    hashed in full, with no end windows); for a larger file `head` and `tail`
-    hold the first- and last-64 KiB hashes and `content` the whole-file or
-    sampled hash. All three are empty strings when the file has never been
-    hashed because its size was unique as of the last scan that covered it. For
-    a file of 10 MiB or more, `content` stays empty until the content phase of a
-    scan (see "`scan` mode" below) has read the file. A record with an empty
-    `content` is never part of a duplicate group, though it still defines the
-    file for tree reconstruction. The `files_signature` index lets `report` read
-    the records in signature order without sorting the table.
+    detection and are not part of the duplicate key. Every record holds the
+    three hashes that "Duplicate detection" below describes. The
+    `files_signature` index lets `report` read the records in signature order
+    without sorting the table.
 
 ### Duplicate detection
 
-Two files are duplicates only when they agree on every rung of this ladder; a
-mismatch at any rung means they are not duplicates. `scan` stores each file's
-hashes, and `report` and `trees` group files by the whole signature — size,
-`head`, `tail`, and `content` — so the grouping is exactly this ladder applied
-across everything scanned into the database, even across separate scans.
+Two files are duplicates when they have the same size and the same three hashes.
+`scan` computes the hashes and stores them in the database. `report` and `trees`
+group the files whose size and hashes all match, whichever scan recorded them.
 
-1.  **Size.** Files of different sizes are never compared. Only files whose size
-    at least one other file shares are hashed at all.
-2.  **Under 10 MiB: whole file.** A file smaller than 10 MiB is hashed in full
-    and compared directly, with no separate end-window step — small files are
-    cheap to read to the last byte, and doing so makes the comparison exact.
-    `head`, `tail`, and `content` all hold this whole-file SHA-256, so such a
-    file's signature is decided entirely by its size and its content.
-3.  **10 MiB and above: head and tail.** For a larger file, the SHA-256 of the
-    first 64 KiB (`head`) and of the last 64 KiB (`tail`) are a cheap gate that
-    eliminates most same-size pairs before any bulk reading: the content hash of
-    the next two rungs is computed only for a file whose size, `head`, and
-    `tail` match another file's, whether that file is scanned in the same run or
-    stored by an earlier scan. A stored file that first gains such a match in a
-    later scan gets its content hash then; until it has one, its `content` is
-    empty and it is not a duplicate. At 10 MiB and above the two windows never
-    overlap.
-4.  **10 MiB and above, content below 50 MiB.** The SHA-256 of the entire file.
-    Agreement here is proof of identical content (barring a SHA-256 collision).
-5.  **10 MiB and above, content 50 MiB and above.** A sampled SHA-256: the 1 MiB
-    window at each gigabyte-aligned offset (0, 1 GiB, 2 GiB, … while inside the
-    file, the final window truncated at end of file) is fed, in order, into one
-    hash. This is **deliberately probabilistic** — the gaps between samples are
-    never read, so two large files that agree on every sample are reported as
-    duplicates without being read in full. It is the price of never reading a
-    150 GB file end to end. Because size is already part of the signature, only
-    equal-size files reach this rung, so their sample boundaries always align.
+`scan` gives every file it records three SHA-256 hashes:
 
-`head`, `tail`, and `content` are one column each. A file below 10 MiB and one
-at or above it never share a size, and neither do a file below 50 MiB and one at
-or above it, so a stored value is never ambiguous between the whole-file,
-end-window, and sampled forms.
+- `head`, the hash of the file's first 64 KiB.
+- `tail`, the hash of the file's last 64 KiB.
+- `content`, the content hash described below.
+
+In a file of 64 KiB or less, the first and the last 64 KiB are both the whole
+file, so all three hashes are the hash of the whole file.
+
+The content hash depends on the file's size:
+
+- Under 100 MiB, it is the SHA-256 of the whole file. Agreement on it is proof
+  of identical content, barring a SHA-256 collision.
+- At 100 MiB and above, it is the SHA-256 of samples, so the file is never read
+  in full. A sample is the 1 MiB at each gigabyte-aligned offset: 0, 1 GiB, 2
+  GiB and so on. The samples are fed into one hash in order. A sample that would
+  run past the end of the file stops there.
+
+The sampled hash is **deliberately probabilistic**. Bytes outside the samples
+and outside the first and last 64 KiB are never read. Two large files that
+differ only in such bytes are reported as duplicates. That is the price of never
+reading a 150 GB file end to end.
+
+Only files of the same size are compared, so their samples always lie at the
+same offsets. A file under 100 MiB and one of 100 MiB or more never share a
+size, so a whole-file hash is never compared with a sampled one.
+
+`scan` reads a file only to hash it, and only when the file is new or has
+changed since its record was written (see "`scan` mode").
 
 ### `scan` mode
 
@@ -439,43 +454,43 @@ results do not depend on the working directory. All operands belong to a single
 scan and are enumerated concurrently: every operand seeds the shared walk worker
 pool. Overlapping operands are harmless — an operand that duplicates another or
 lies under another is dropped before walking, so every file is reached exactly
-once and produces one database record. With `-x`, though, an operand under
-another one is kept and walked on its own when any directory from it (from its
-directory, for a regular file) up to but not including the operand covering it
-is on a different filesystem than that operand, because that operand's walk does
-not enter such a directory and so does not reach it.
+once and produces one database record. An operand under another one is kept,
+though, and walked on its own when any directory from it (from its directory,
+for a regular file) up to but not including the operand covering it is a default
+exclude, is not on a persistent filesystem (see "Rules for the walk"), or, with
+`-x`, is on a different filesystem than that operand, because that operand's
+walk does not enter such a directory and so does not reach it.
 
-An operand that is a symlink (never followed, not even as an operand), socket,
-FIFO, or device node, or a directory named `.zfs`, is not scanned. `scan` prints
-a one-line warning naming the path and what it is, counts it as skipped, and
-drops it from the scanned operands before reading the database. Another operand
-beneath it is still scanned. The records stored beneath it are not deleted: they
-are treated like any other record outside the scanned operands, including the
-content-phase exception below. If it lies under another operand, they are under
-that operand instead, and are treated like any other record there. This is not
-an error: a scan whose every operand is dropped walks nothing and exits 0.
+An operand is not scanned when it is:
+
+- a symlink, which `scan` never follows, not even as an operand;
+- a socket, FIFO or device node;
+- at or inside a directory named `.zfs`.
+
+An operand reached through a symlink into a `.zfs` directory is not scanned
+either.
+
+This holds even when the operand lies under another operand. `scan` prints a
+one-line warning naming the path and what it is, counts it as skipped, and drops
+it from the scanned operands before reading the database. An operand beneath a
+symlink operand is still scanned. The records stored beneath the dropped operand
+are not deleted: they are treated like any other record outside the scanned
+operands. If it lies under another operand, they are under that operand instead,
+and are treated like any other record there. This is not an error: a scan whose
+every operand is dropped walks nothing and exits 0. An operand that is not on a
+persistent filesystem (see "Rules for the walk") is dropped the same way. The
+line `scan` prints for it is not a warning, though, and it is not counted as
+skipped.
 
 `scan` synchronizes the database with the filesystem state under the scanned
 operands:
 
-- Only a file whose size at least one other file shares is ever read: a
-  size-unique file cannot be a duplicate, so it is recorded without hashes
-  (`head`, `tail`, and `content` empty). The size census covers every file
-  walked this scan plus every database record outside the scanned operands, so a
-  possible duplicate of a separately scanned tree is still recognized.
-- A file not yet in the database is inserted: hashed when its size is shared,
-  without hashes otherwise.
+- A file not yet in the database is hashed and inserted.
 - A file already in the database is **skipped without reading its contents**
   when its lstat size equals the recorded size and its lstat mtime is not newer
-  than the recorded mtime. This is what makes a daily rescan cheap. Exception:
-  an unchanged file whose record lacks hashes is hashed — and its record updated
-  — once its size becomes shared, so hashing deferred by size-uniqueness happens
-  as soon as it could matter. Likewise, an unchanged file of 10 MiB or more
-  whose record has no `content` hash is read for one by the content phase below
-  once its size, `head`, and `tail` match another record's.
-- A file whose mtime is newer than recorded, or whose size differs, is processed
-  as if new: re-hashed, or recorded without hashes, per the shared-size rule.
-  Change detection compares the mtime to the nanosecond, as finely as the
+  than the recorded mtime. This is what makes a daily rescan cheap.
+- A file whose mtime is newer than recorded, or whose size differs, is hashed
+  again. Change detection compares the mtime to the nanosecond, as finely as the
   filesystem records it, so a same-size rewrite counts as a change whenever the
   filesystem gives it a later mtime than recorded, even within the same second.
 - A database record whose path lies under one of the scanned operands but was
@@ -483,29 +498,26 @@ operands:
   deleted files. It also removes records for paths that failed to stat or hash
   this run: the database only ever contains signatures verified by the most
   recent scan that covered them (a subsequent successful scan re-adds such
-  files). A failure in the content phase below removes nothing: the record is
-  left as it is.
+  files).
 - Database records outside the scanned operands are untouched, so disjoint trees
-  can be scanned on different schedules into the same database. The one
-  exception is the content phase below: a stored file of 10 MiB or more without
-  a `content` hash is read for one, wherever it lies, once its size, `head`, and
-  `tail` match another record's. If that file is gone or has changed since its
-  record was written, the record is left as it is.
-- With `-x`, a record below a directory the walk did not enter because that
-  directory is on another filesystem than its operand counts as outside the
-  scanned operands: it is not deleted, and its size joins the size census. A
-  filesystem mounted under an operand can therefore be scanned on its own
-  schedule into the same database. Records below an operand at or inside such a
-  directory are not kept this way, since that operand's own walk verifies them.
+  can be scanned on different schedules into the same database.
+- A record at or below a path the walk left out counts as outside the scanned
+  operands, so it is not deleted. The walk leaves out a path that:
+    - is a default exclude;
+    - is not on a persistent filesystem;
+    - with `-x`, is a directory on another filesystem than its operand.
 
-`scan` runs **five sequential phases over the whole scan**. Parallelism lives
-inside the walk, hash and content phases; batched database writes begin during
-the hash phase:
+    A filesystem mounted under an operand can therefore be scanned on its own
+    schedule into the same database. Records below an operand at or inside such
+    a path are not kept this way, since that operand's own walk verifies them.
+
+`scan` runs **four sequential phases over the whole scan**. Parallelism lives
+inside the walk and hash phases, and batched database writes begin during the
+hash phase:
 
 1.  **load** — read the existing records. Each record under the operands is kept
-    in memory, by path, with its size, its mtime and whether it has hashes, for
-    the walk to compare each file with; the size of every other record joins the
-    size census.
+    in memory, by path, with its size and its mtime, for the walk to compare
+    each file with.
 2.  **walk + stat** — enumerate the trees under all `PATH` operands concurrently
     with the walk worker pool: every operand seeds the shared queue, and each
     worker reads one directory at a time, handing discovered subdirectories back
@@ -513,48 +525,23 @@ the hash phase:
     (while the directory's metadata is still hot). Sequential directory
     enumeration is metadata-latency-bound and takes hours at tens of millions of
     files; per-directory parallelism is what makes the walk tractable on large
-    or busy pools. The walk builds the size census and resolves unchanged
-    already-hashed files on the fly; every other file is carried to the hash
-    phase as a (path, size, mtime) record.
-3.  **hash** — with the census complete, each carried file's size decides its
-    fate. Size-unique files are never read: new or changed ones are recorded
-    without hashes in the update phase, unchanged unhashed ones simply keep
-    their records. Every file with a shared size is hashed by the worker pool as
-    described in "Duplicate detection" above: a file under 10 MiB in full, which
-    gives its `head`, `tail`, and `content` alike, and a larger file only in its
-    end windows, which give its `head` and `tail`; its content hash is left to
-    the content phase. Zero-length files have constant hashes and are never
-    opened. Files are hashed in **inode order** (minimizing seeks on spinning
-    disks), and paths that are hard links to the same inode are **read once**,
-    all sharing the one result — a hard-link backup farm costs one read per
-    inode, not per path. The phase total counts actual reads, so progress and
-    ETA are meaningful. Completed records are committed in batched transactions
-    **while hashing runs**, so a scan interrupted after hours keeps everything
-    hashed so far and the next scan resumes cheaply, skipping records already
-    written.
-4.  **update** — commit the final partial batch, the hash-less records for
-    size-unique new and changed files, and the deletions for records the scan
-    did not verify (vanished files, plus paths that failed to stat or hash).
-5.  **content** — find every record of 10 MiB or more without a `content` hash
-    whose size, `head`, and `tail` equal another record's, anywhere in the
-    database: records from this scan and records stored by earlier scans, inside
-    or outside the scanned operands. SQLite finds them, so only the records to
-    be read are kept in memory, never every file's hashes. Every record sharing
-    their size, `head`, and `tail`, including one that already has a `content`
-    hash, has its file checked with `lstat` first. A file that is gone, is no
-    longer a regular file, or has changed (a different size, or an mtime newer
-    than recorded) keeps its record as it is and does not count as a match for
-    the others. Any other `lstat` error is warned about and counted as skipped,
-    with the same result. If such a record has no `content` hash, it stays out
-    of duplicate groups; if it has one, it is still reported until a scan
-    covering its own tree updates or removes it. The files that pass and have no
-    `content` hash are read only if at least two of those records pass, so a
-    file whose only matches are stale costs no read; a file that already has a
-    `content` hash is never read again. They are read by a worker pool as in the
-    hash phase, in inode order and once per inode, and their content hashes are
-    committed in batches. A failed read is warned about and counted as skipped;
-    its record keeps an empty `content`, so it is not a duplicate, and a later
-    scan tries again.
+    or busy pools. The walk compares each file with its record as it goes, and
+    an unchanged file needs nothing more. Every new or changed file is carried
+    to the hash phase as a (path, size, mtime) record.
+3.  **hash** — the worker pool hashes every carried file as described in
+    "Duplicate detection" above, which gives the file its `head`, `tail` and
+    `content`. Zero-length files have constant hashes and are never opened.
+    Files are hashed in **inode order**, which minimizes seeks on spinning
+    disks. Paths that are hard links to the same inode are **read once**, and
+    all share the one result. A hard-link backup farm therefore costs one read
+    per inode, not per path. The phase total counts actual reads, so its
+    progress and its time remaining are meaningful. Completed records are
+    committed in batched transactions **while hashing runs**. A scan interrupted
+    after hours therefore keeps everything hashed so far, and the next scan
+    resumes cheaply, skipping records already written.
+4.  **update** — commit the final partial batch of hashed records. Then delete
+    the records the scan did not verify: those of vanished files, and of paths
+    that failed to stat or hash.
 
 Rules for the walk:
 
@@ -565,33 +552,111 @@ Rules for the walk:
 - Never descend into a directory named `.zfs` (ZFS snapshot pseudo-dirs; walking
   them would list every file once per snapshot), not even when it is an operand;
   such an operand is dropped the same way.
+- Never record the scan's own database. Once the database and its `.lock` file
+  are open, `scan` notes the device and inode of the database file, its `-wal`
+  and `-shm` files and its `.lock` file, and the walk passes over a file with
+  one of them, however it reaches it: as an operand, below one, or through a
+  symlinked directory. It prints no line for such a file and does not count it
+  as skipped. A record that an earlier scan left for one of them is deleted,
+  like the record of any file the scan no longer verifies. There is no
+  `-journal` file during the walk, because the database is in WAL mode then (see
+  "Database").
 - Filesystem boundaries are crossed by default. With `-x` (long form
   `--one-file-system`, following the GNU `du`/`rsync` convention), never descend
   into a directory on a different filesystem than its `PATH` operand; each
-  operand is bounded by its own filesystem. The records below such a directory,
-  unless they lie below an operand at or inside that directory, count as outside
-  the scanned operands, as described in "`scan` mode" above: they are not
-  deleted, and their sizes join the size census.
-- On any per-path error (permission denied, file vanished between passes,
-  unreadable): print a one-line warning to stderr, skip the path, and continue.
-  Per-file errors never abort the run; the final summary reports how many were
-  skipped. As specified above, a skipped path that has a database record from an
-  earlier scan loses that record, unless it failed only in the content phase, or
-  is an operand dropped before the database was read whose record counts as
-  outside the scanned operands; an unreadable directory subtree likewise loses
-  its records (accepted: the database mirrors what the latest scan could
-  actually verify).
+  operand is bounded by its own filesystem. The records below such a directory
+  count as outside the scanned operands, as described in "`scan` mode" above:
+  they are not deleted. That does not hold below an operand at or inside that
+  directory.
+- Never record anything that is not on a persistent filesystem. A filesystem is
+  not persistent when the kernel makes it up or keeps it in memory: one of type
+  `proc`, `sysfs`, `devtmpfs`, `devpts`, `tmpfs`, `ramfs`, `cgroup`, `cgroup2`,
+  `debugfs`, `tracefs`, `securityfs`, `pstore`, `bpf`, `configfs`, `fusectl`,
+  `mqueue`, `hugetlbfs`, `efivarfs`, `binfmt_misc`, `autofs`, `nsfs`,
+  `rpc_pipefs`, `selinuxfs` or `devfs` (the macOS filesystem of `/dev`). After
+  it names the database and before it takes the lock, `scan` lists the mounted
+  filesystems, from `/proc/self/mountinfo` on Linux and from the system's list
+  of mounted filesystems on macOS (on any other system it lists none), and notes
+  the device ID of each one of those types. On Linux that is the device ID the
+  list gives, so a filesystem that a later mount hides still gives its own. On
+  macOS it is read with `lstat` on the mount point, and where one filesystem is
+  mounted over another on the same mount point, the one mounted last counts. If
+  `scan` cannot list them, it fails (exit 1). The walk then never enters a
+  directory, and never records a file, on one of those devices, however it
+  reaches it: as an operand, below one, or through a bind mount, which keeps the
+  device ID of what it binds. No flag turns this off. For each operand,
+  directory or file it leaves out this way, `scan` prints a line on stderr
+  naming it and the type of its filesystem. It prints that line as it prints a
+  warning, so the line never lands inside a progress display:
 
-Concurrency: the walk phase (which also stats files), the hash phase, and the
-content phase each use a worker pool of `--workers` workers (default
-`runtime.NumCPU()`); the walk parallelizes across directories, hashing across
-files. `--workers` must be at least 1: a smaller value is a usage error,
-reported in one line on stderr with exit 2 before anything is scanned. All three
-phases are seek-bound on spinning disks, so raising `--workers` well past the
-core count can help on pools with many spindles. The main goroutine owns
-partitioning, database writes, and the progress counts, which each progress
-display draws from a goroutine of its own; progress display must never block the
-workers.
+    ```
+    scan: skipped /dev/shm (tmpfs, not a persistent filesystem)
+    ```
+
+    That line is not a warning, and the path is not counted as skipped. An
+    earlier scan's records at or below it count as outside the scanned operands,
+    as described in "`scan` mode" above: they are not deleted. That does not
+    hold below an operand at or inside it.
+
+- Below an operand, never descend into a default exclude: a path that holds the
+  kernel's view of the running system, or temporary files, so that
+  `sfdupes scan /` walks only the files worth comparing. The default excludes
+  depend on the system, and `sfdupes scan --help` lists those of the system it
+  runs on:
+    - On Linux: `/proc`, `/sys`, `/dev`, `/run`, `/tmp` and `/var/tmp`.
+    - On macOS: `/dev`, `/private/tmp`, `/private/var/tmp`, `/private/var/vm`,
+      `/System/Volumes/VM` and `/System/Volumes/Data`. A walk of `/` reaches
+      everything in `/System/Volumes/Data` through the firmlinks, so walking it
+      as well would record each of those files twice.
+    - On Windows, relative to the root of the drive an operand lies on: the
+      page, swap and hibernation files `pagefile.sys`, `swapfile.sys` and
+      `hiberfil.sys`, and the directories `System Volume Information`,
+      `$Recycle.Bin`, `Windows\Temp` and `Users\*\AppData\Local\Temp`, where `*`
+      matches one path component, as it does in any default exclude. sfdupes
+      does not build for Windows yet, so this list is not used.
+    - On any other system there are none.
+
+    `--no-default-excludes` turns them all off; what is not on a persistent
+    filesystem stays left out. An operand at or inside a default exclude is
+    still walked, so `sfdupes scan /tmp/x` works, unless it is not on a
+    persistent filesystem. For each default exclude its walk does not enter,
+    `scan` prints a line on stderr naming it, as it prints a warning:
+
+    ```
+    scan: skipped /var/tmp (default exclude)
+    ```
+
+    That line is not a warning, and the directory is not counted as skipped. A
+    default exclude that is not on a persistent filesystem, as `/proc` is, gets
+    the line for its filesystem instead. One that is itself an operand gets no
+    line, since it is walked as that operand. When the walk does not enter a
+    default exclude, the records below it count as outside the scanned operands,
+    as described in "`scan` mode" above: they are not deleted. That does not
+    hold below an operand at or inside it.
+
+- On a per-path error, such as permission denied or an unreadable file: print a
+  one-line warning to stderr, skip the path, and continue. Per-file errors never
+  abort the run; the final summary reports how many were skipped. As specified
+  above, a skipped path that has a database record from an earlier scan loses
+  that record. An unreadable directory subtree likewise loses its records. This
+  is accepted: the database mirrors what the latest scan could actually verify.
+  The exception is an operand dropped before the database was read, whose record
+  counts as outside the scanned operands.
+- A file or directory removed while the scan runs is not an error. The scan
+  prints no line for it and does not count it as skipped. A path gone when the
+  walk reaches it gets no record. A file gone when the hash phase opens it gets
+  none either. The records an earlier scan left at or below such a path are
+  deleted.
+
+Concurrency: the walk phase, which also stats files, and the hash phase each use
+a worker pool of `--workers` workers (default `runtime.NumCPU()`). The walk
+parallelizes across directories, and hashing across files. `--workers` must be
+at least 1: a smaller value is a usage error, reported in one line on stderr
+with exit 2 before anything is scanned. Both phases are seek-bound on spinning
+disks, so raising `--workers` well past the core count can help on pools with
+many spindles. The main goroutine owns the database writes and the progress
+counts. Each progress display draws the counts from a goroutine of its own, and
+must never block the workers.
 
 `scan` writes nothing to stdout. The summary line on stderr reports the files
 seen this run broken down by disposition, plus skips:
@@ -614,9 +679,7 @@ output whether or not the scanned filesystem is still mounted.
 
 Processing:
 
-- Records without a `content` hash (see "Database" above) are excluded: their
-  content is unknown, so they are never reported as duplicates.
-- Group the remaining records by the key `(size, head, tail, content)`.
+- Group the records by the key `(size, head, tail, content)`.
 - Every group with two or more paths is a duplicate group.
 - Within each group, sort paths lexicographically (byte order). The first path
   is the group's `first`; every other path is a `dupe`.
@@ -670,9 +733,7 @@ records, split on `/`.
 Definitions:
 
 - A file's **signature** is `(size, head, tail, content)` — mtime is
-  informational and excluded. A record without a `content` hash has unknown
-  content: its signature is treated as unique to that file, so a tree containing
-  such a file never compares equal to any other tree.
+  informational and excluded.
 - A directory's **digest** is a SHA-256 Merkle digest computed bottom-up:
   serialize the directory's child entries — for a file child, its name and
   signature; for a subdirectory child, its name and that subdirectory's digest —
@@ -746,8 +807,6 @@ database file size	2147483648 (2.0 GiB)
 modified	2026-10-16T12:02:50Z
 schema version	1
 records	12345678
-records with head and tail hashes	1234567
-records with content hash	123456
 size of recorded files	150000000000000 (136.4 TiB)
 ```
 
@@ -760,10 +819,8 @@ size of recorded files	150000000000000 (136.4 TiB)
   database is in WAL mode, the newest changes may be in the `-wal` file alone.
 - `schema version` is the database's `PRAGMA user_version`. A database with
   another version than this build's is refused, as by `report`.
-- `records` is the number of records. `records with head and tail hashes` and
-  `records with content hash` count the records that have those hashes (see
-  "Database"), and `size of recorded files` adds up the sizes of all records, in
-  bytes, then in human units.
+- `records` is the number of records. `size of recorded files` adds up the sizes
+  of all records, in bytes, then in human units.
 
 `info` runs in two phases, each with its own progress display on stderr (see
 "Progress"): `open` opens the database; `count` reads the schema version and
@@ -779,27 +836,21 @@ Use the progress-bar library for all progress of `scan`, `report`, `trees` and
 stderr.
 
 `scan`, `report`, `trees` and `info` must always show that they are working and
-not hung. Each phase gets its own display from the moment it starts, naming the
-phase and its place among the command's phases and showing its progress, its
-elapsed time and its estimated time remaining (ETA).
+not hung. Each phase gets its own display from the moment it starts. The display
+names the phase and its place among the command's phases. It shows the phase's
+progress, its elapsed time and its time remaining.
 
-A scan has five phases (`[1/5] load`, `[2/5] walk`, `[3/5] hash`,
-`[4/5] update`, `[5/5] content`):
+A scan has four phases (`[1/4] load`, `[2/4] walk`, `[3/4] hash`,
+`[4/4] update`):
 
 - `load` counts the records first, then reads them against that count. While the
   count runs, the display says it is counting the records.
 - `walk` has no exact total. Its estimate is the number of records the last scan
-  left under the operands, known once `load` is done and shown with a `~`. Once
-  the walk passes the estimate, or when there are no such records, as on a first
-  scan, the ETA is unknown.
+  left under the operands, known once `load` is done and shown with a `~`. The
+  time remaining is unknown once the walk passes the estimate, and when there
+  are no such records, as on a first scan.
 - `hash` and `update` have exact totals. Only files that actually need hashing
-  appear in the hash total, so its ETA is meaningful.
-- `content` first counts the records whose files it checks with `lstat`, which
-  SQLite does by adding up the number of records with each matching size,
-  `head`, and `tail`, without fetching the records. It then says it is searching
-  the database until SQLite returns the first record; the checks, and their rate
-  and ETA, start there. The files to read then get a display of their own, with
-  their count as its total.
+  appear in the hash total, so its time remaining is meaningful.
 
 `trees` has four phases (`[1/4] open`, `[2/4] read`, `[3/4] group`,
 `[4/4] write`, see "`trees` mode"):
@@ -824,8 +875,8 @@ A scan has five phases (`[1/5] load`, `[2/5] walk`, `[3/5] hash`,
 - `open` has no total. While it opens the database, waiting on a busy one
   included, the display says it is opening the database.
 - `count` has no total either, because one query counts everything: the display
-  says it is counting the records until the query returns, and its ETA is
-  unknown.
+  says it is counting the records until the query returns, and its time
+  remaining is unknown.
 
 Each display is one line holding:
 
@@ -833,37 +884,74 @@ Each display is one line holding:
 - a `[m/n] x%` display (items processed / total items, percent); before a phase
   has a total, the items processed, or what the phase is waiting for
 - current rate (items/s), naming the items the phase counts: files, records,
-  directories or groups
-- elapsed time
-- estimated time remaining, or `unknown`
+  directories or groups. It covers the items completed over the last 5 seconds,
+  or, when stderr is not a terminal, since the line before, so it falls to 0
+  while nothing completes, and a burst of items after a wait shows as a burst
+  rather than as a steady rate. Once no item has completed for 10 seconds, the
+  word `stalled` and where the phase waits take the rate's place (see below).
+- elapsed time, labelled `elapsed`
+- time remaining, labelled `remain`: a duration such as `12m9s`, or `unknown`.
+  It comes from the phase's average rate since it started counting, so that it
+  does not swing with each burst.
 
-Example shape (exact layout is flexible, content is not):
+Example lines, as printed when stderr is not a terminal:
 
 ```
-[3/5] hash: [12345/98765] 12% |████      | 92 files/s elapsed 2:32 eta 17:54
-[2/5] walk: [1234567/~1200000] 103%, 5120 files/s, elapsed 4m1s, eta unknown
+[3/4] hash: [12345/98765] 12%, 92 files/s, elapsed 2m32s, remain 17m44s
+[2/4] walk: [1234567/~1200000] 103%, 5120 files/s, elapsed 4m1s, remain unknown
+[3/4] hash: [12345/45678] 27%, stalled disk/db, elapsed 4m30s, remain 12m9s
 ```
 
+When no item has completed for 10 seconds, as while one large file is read, a
+disk is slow or the database is busy, the line says `stalled` and where the
+phase waits in place of the rate, which would read 0: `disk` for files, `db` for
+the database, `out` for stdout, and two of them, as `disk/db`, for a phase that
+may wait on either. `walk` says `disk`. `hash` says `disk/db`, as it reads files
+and writes their records to the database between them. `load`, `update` and the
+`read` phase of `trees` say `db`. `trees`' `write` says `out`, and its `group`,
+which works in memory, says `cpu`. The `read` phase of `report` writes the
+report while it reads the records, so it says `db/out`. A phase still waiting
+for its total already says what it waits for, and says nothing more.
+
 Additional requirements:
 
-- On a terminal, a phase with an exact total (every phase but `scan`'s `walk`,
-  the `open` phase of `report` and `trees`, and both phases of `info`, once it
-  has counted what it will do) is drawn as its line followed by the progress-bar
-  library's bar, 10 columns wide, which shows the percent in place of the line's
-  own. Any other phase, and a phase whose bar has no room, is drawn as the
-  library's spinner followed by its line. Each display is drawn again several
-  times a second, so its elapsed time keeps moving while a phase waits for its
-  next item.
+- On a terminal, every display starts with the progress-bar library's spinner in
+  its first column, followed by its line. Each display is drawn again several
+  times a second, so its spinner turns and its elapsed time keeps moving while a
+  phase waits for its next item.
+- On a terminal, a phase with an exact total ends its line with its percent and
+  a bar 10 columns wide. This percent takes the place of the line's own. The bar
+  stays at the terminal's right edge, so it does not move as the line grows or
+  shrinks. A phase with nothing to do shows no bar. Every phase has an exact
+  total once it has counted what it will do, except these:
+    - `scan`'s `walk`;
+    - the `open` phase of `report` and `trees`;
+    - both phases of `info`.
+
+    On a terminal 100 columns wide:
+
+    ```
+    ⠹ [3/4] hash: [12345/98765], 92 files/s, elapsed 2m32s, remain 17m44s            12% |█         |
+    ```
+
 - On a terminal no line reaches the terminal's last column, however narrow the
-  terminal is. The phase and its place, the progress, the elapsed time and the
-  ETA are kept whole: a line too wide for the terminal leaves out its rate first
-  (or what the phase is waiting for), and a bar with no room beside those four
-  gives way to the spinner. Only when those four alone are too wide, as on a
-  terminal narrower than about 70 columns hours into a scan of millions of
-  files, is the line cut short at the terminal's edge, so the end of the ETA is
-  lost first. A terminal made narrower while a phase runs gets the same: the
-  next draw erases the line within the new width and fits the line to it, and
-  the display goes on redrawing in place.
+  terminal is. A line too wide for the terminal first loses whichever of these
+  it shows: its rate, the words of a stalled phase, or what the phase is waiting
+  for. The other four parts are kept whole:
+    - the phase and its place;
+    - the progress;
+    - the elapsed time;
+    - the time remaining.
+
+    The line loses its bar only when those four and the bar do not fit. It is
+    cut short at the terminal's edge only when those four alone are too wide,
+    and then the end of the time remaining is lost first. That happens hours
+    into a scan of millions of files, on a terminal narrower than about 75
+    columns. On a terminal 100 columns wide, the stalled line of the example
+    above keeps its words and its bar. The next draw fits the line to a terminal
+    made narrower while a phase runs. It erases the old line within the new
+    width, and the display goes on redrawing in place.
+
 - When stderr is not a terminal (a pipe, a file, `/dev/null`), do not emit ANSI
   redraws: print the line the moment each phase starts, every 5 seconds while it
   runs (whether or not an item has completed, and never more often), and once
@@ -988,13 +1076,22 @@ entrypoints are:
 - `script/install-precommit` — install the git pre-commit hook, as
   `.git/hooks/pre-commit`, that runs `script/precommit`.
 
-Every `docker build` in `script/` passes a new `CACHEBUST` build argument, which
-every stage of the `Dockerfile` declares first, so every `RUN` step runs again
-each time. On an unchanged tree Docker would otherwise serve the gate steps from
-its cache, and the build would pass having run no test and no linter. Go's build
-cache is kept between builds on the steps that compile, so only what changed is
-compiled again; the tests run with `-count=1`, so none reports a stored result.
-Every run downloads the Go modules again and needs the network.
+Every `docker build` in `script/` passes a new `CACHEBUST` build argument. In
+every stage of the `Dockerfile`, `ARG CACHEBUST` comes right after the steps
+that install system packages and download the Go modules, or right after `FROM`
+in a stage with neither, and every step that lints, tests or compiles comes
+after it, so every `RUN` step after it runs again each time. On an unchanged
+tree Docker would otherwise serve the gate steps from its cache, and the build
+would pass having run no test and no linter. The layers above that line stay in
+Docker's build cache until the base image, their own lines, `go.mod` or `go.sum`
+change, or until that cache is cleared; only then are the packages installed and
+the modules downloaded again. Go's build cache is kept between builds on the
+steps that compile, so only what changed is compiled again; the tests run with
+`-count=1`, so none reports a stored result. `golangci-lint run` also keeps
+golangci-lint's cache, and takes a package's findings from it only when the
+package's files and those of the packages it imports, `go.mod`, the linters and
+their settings in `.golangci.yml`, and the golangci-lint version are all
+unchanged.
 
 ## Build
 
@@ -1058,10 +1155,6 @@ All of the following, run in this directory, must pass:
     ./sfdupes report
     ```
 
-    (The database lives in a temp directory of its own: inside `$d`, the scan
-    would record it, and its empty lock file would join the `empty1`/`empty2`
-    group.)
-
     Expected from the first `report`: `one.bin`/`copy.bin`/`copy2.bin` form one
     group (two dupe rows, `first` is the lexicographically smallest path);
     `t1/f1`/`t2/f1`/`t3/f1` form one group; `t1/sub/f2`/
@@ -1090,8 +1183,8 @@ Tracked in [TODO.md](TODO.md).
 ## Non-goals
 
 - No byte-for-byte compare, and no deletion or linking of duplicates. Files that
-  match are compared by a SHA-256 of the whole file below 50 MiB, and only by
-  samples at 50 MiB and over. The reports are advisory; acting on them is the
+  match are compared by a SHA-256 of the whole file below 100 MiB, and only by
+  samples at 100 MiB and over. The reports are advisory; acting on them is the
   user's job.
 - No persistence beyond the SQLite database described above; no export/import
   formats.

REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-10-15
+last_modified: 2026-10-18
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -159,8 +159,11 @@ style conventions are in separate documents:
     one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
     exit non-zero with `parallel golangci-lint is running` — a status a caller
     cannot tell from real findings. Both have produced wrong verdicts in this
-    org, in both directions. A container has its own golangci-lint cache, its
-    own `TMPDIR` and a digest-pinned binary, so neither is reachable.
+    org, in both directions. A container has its own `TMPDIR`, so the lock is
+    out of reach. The lint phase does keep golangci-lint's cache between check
+    builds (below), but it lints every checkout at `/src`, and a finding is
+    taken from that cache only for the same files, settings and golangci-lint
+    version.
 
 - **Any build that runs checks is given a new `CACHEBUST` value.** Docker
   invalidates a `COPY` layer only when the copied content changes, so on an
@@ -170,15 +173,21 @@ style conventions are in separate documents:
   id, so no two builds share a value, not even the three in one
   `script/cibuild`. `script/lint`, `script/test`, `script/cibuild` and
   `script/docker` are the four, and there is no fifth — `script/check` runs the
-  two gate phases and `script/fmt-check`, and builds no image of its own. Every
-  stage of the `Dockerfile` declares `ARG CACHEBUST` as its first line after
-  `FROM`, and a new value reruns every `RUN` step after that line; `COPY` steps
-  are compared by content and need nothing. A stage without the `ARG` line is
-  served from cache on an unchanged tree, so a repository re-vendors the scripts
-  and adds the `ARG` lines in one commit. The scripts do not pass `--no-cache`:
-  it reruns every step too, but it also empties every cache mount, and Go's
-  build cache, which the canonical Go `Dockerfile` below mounts so that compiled
-  packages survive between check builds, would start empty every time. A bare
+  two gate phases and `script/fmt-check`, and builds no image of its own. In
+  every stage of the `Dockerfile`, `ARG CACHEBUST` comes right after the steps
+  that install system packages and download Go's modules, or right after `FROM`
+  in a stage with neither, and every step that lints, tests or compiles comes
+  after it. A step that installs anything else as well, such as a
+  `script/bootstrap` that also installs node packages, comes after it too. A new
+  value reruns every `RUN` step after that line; `COPY` steps are compared by
+  content and need nothing. Docker keeps the layers above the line until the
+  base image, their own lines or the files they copy change. A stage without the
+  `ARG` line is served from cache on an unchanged tree, so a repository
+  re-vendors the scripts and adds the `ARG` lines in one commit. The scripts do
+  not pass `--no-cache`: it reruns every step too, but it also builds the layers
+  above the line again and empties every cache mount, so Go's build cache and
+  golangci-lint's, which the canonical Go `Dockerfile` below mounts so that they
+  survive between check builds, would start empty every time. A bare
   `docker build .` is not evidence that anything ran: a sub-second build
   reporting success is a cache hit, not a result. Never invalidate by pruning —
   `docker builder prune` and friends destroy a build cache shared with every
@@ -194,19 +203,25 @@ style conventions are in separate documents:
   `Dockerfile`:
 
     ```dockerfile
-    # Every stage declares ARG CACHEBUST first: script/ passes a new value
-    # on every build, which reruns every RUN step after it. The steps that
-    # compile mount Go's build cache, which survives from build to build.
+    # In every stage ARG CACHEBUST comes right after the steps that install
+    # system packages and download Go's modules, or right after FROM in a
+    # stage with neither, and every step that lints, tests or compiles
+    # comes after it. script/ passes a new value on every build, which
+    # reruns every RUN step after it. Docker keeps the layers above it
+    # until the base image, their own lines or go.mod and go.sum change.
+    # The steps that compile mount Go's build cache, and golangci-lint run
+    # also mounts golangci-lint's; both survive from build to build.
 
     # Lint phase
     # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
     FROM golangci/golangci-lint@sha256:... AS lint
-    ARG CACHEBUST
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
+    ARG CACHEBUST
     COPY . .
     RUN --mount=type=cache,target=/root/.cache/go-build \
+        --mount=type=cache,target=/root/.cache/golangci-lint \
         golangci-lint run --config .golangci.yml ./...
 
     # Test phase. -race needs cgo and so a C compiler, which the Debian Go
@@ -214,10 +229,10 @@ style conventions are in separate documents:
     # cache also holds test results, which go test would otherwise replay.
     # golang:1.x, YYYY-MM-DD
     FROM golang@sha256:... AS test
-    ARG CACHEBUST
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
+    ARG CACHEBUST
     COPY . .
     RUN --mount=type=cache,target=/root/.cache/go-build \
         go test -count=1 -timeout 90s -race -cover ./... || \
@@ -225,19 +240,19 @@ style conventions are in separate documents:
           go test -count=1 -timeout 90s -race -v ./...; exit 1; }
 
     # Build stage. Nothing is wanted from either phase above; the copies
-    # are what make BuildKit build them first, so this stage cannot run
-    # unless lint and test passed.
+    # are what make BuildKit build them first, so nothing after them can
+    # run unless lint and test passed.
     # golang:1.x-alpine, YYYY-MM-DD
     FROM golang@sha256:... AS builder
-    ARG CACHEBUST
-    COPY --from=lint /src/go.sum /dev/null
-    COPY --from=test /src/go.sum /dev/null
     RUN apk add --no-cache git
-    # A tar-stream context keeps the sender's file owners, which git refuses.
-    RUN git config --system --add safe.directory /src
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
+    ARG CACHEBUST
+    COPY --from=lint /src/go.sum /dev/null
+    COPY --from=test /src/go.sum /dev/null
+    # A tar-stream context keeps the sender's file owners, which git refuses.
+    RUN git config --system --add safe.directory /src
     COPY . .
 
     # The VERSION build arg when one is given, otherwise
@@ -274,16 +289,26 @@ style conventions are in separate documents:
     - Keep the runtime stage last, and if you add a stage after it, give it the
       same two copies. A plain `docker build .` builds the last stage's chain
       and nothing else.
-    - Only Go's build cache is mounted (`/root/.cache/go-build`, where Go keeps
-      it for root), and only on the steps that compile: `golangci-lint run`,
-      both `go test` runs and `go build`. It keeps compiled packages between
-      check builds, and Go reuses one only when all its inputs are unchanged, so
-      it saves the compile without skipping a check. Nothing else is kept:
-      golangci-lint's own cache would replay stored findings in place of a lint
-      run, and Go builds from whatever files a kept module cache holds without
-      checking them again (only `go mod verify` does), so a file changed there
-      would go unnoticed. Go's build cache also holds test results, which is why
-      both `go test` runs carry `-count=1`.
+    - Check builds keep these, and none of them can hand back a stale result:
+        - The layers above `ARG CACHEBUST`: the system packages and Go's
+          modules. Docker installs the packages again when the base image or the
+          install line changes, and downloads the modules again when `go.mod` or
+          `go.sum` changes. Go checks every module against `go.sum` as it
+          downloads it, and no later build can change a kept layer. The modules
+          are kept in a layer rather than a cache mount because a cache mount is
+          shared by every build on the host, and Go builds from whatever files
+          it holds without checking them again (only `go mod verify` does), so a
+          file changed there would go unnoticed.
+        - Go's build cache (`/root/.cache/go-build`, where Go keeps it for
+          root), mounted on the steps that compile: `golangci-lint run`, both
+          `go test` runs and `go build`. Go reuses a compiled package only when
+          all its inputs are unchanged. The cache also holds test results, which
+          is why both `go test` runs carry `-count=1`.
+        - golangci-lint's cache (`/root/.cache/golangci-lint`, where the pinned
+          image keeps it), mounted on `golangci-lint run`. golangci-lint reuses
+          a package's findings only when the package's files and those of every
+          package it imports, `go.mod`, the linters and their settings in
+          `.golangci.yml`, and the golangci-lint version are all unchanged.
     - If the project uses `//go:embed` directives that reference build artifacts
       (e.g. a web frontend compiled in a separate stage), the lint phase must
       create placeholder files so the embed directives resolve. Example:
@@ -292,12 +317,20 @@ style conventions are in separate documents:
       in the lint phase. The `golangci/golangci-lint` image is Debian-based and
       has no `apk`, so install with `apt-get` under the Debian package name
       (`libvips-dev`, where alpine says `vips-dev`), and delete the package
-      lists in the same `RUN`, so the layer does not keep them:
+      lists in the same `RUN`, so the layer does not keep them. The test phase,
+      on the Debian Go image, installs the libraries its tests need the same
+      way. Either install goes right after `FROM`, above `ARG CACHEBUST`, so
+      Docker keeps it until the base image or the install line changes:
 
         ```dockerfile
+        FROM golangci/golangci-lint@sha256:... AS lint
         RUN apt-get update \
             && apt-get install -y --no-install-recommends libvips-dev \
             && rm -rf /var/lib/apt/lists/*
+        WORKDIR /src
+        COPY go.mod go.sum ./
+        RUN go mod download
+        ARG CACHEBUST
         ```
 
     - `.dockerignore` lets `.git` into the build context. It keeps out every git

cancel_test.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"crypto/sha256"
 	"database/sql"
 	"errors"
 	"fmt"
@@ -168,8 +169,8 @@ func assertRecordsIntact(t *testing.T, db *sql.DB, before []string) {
 
 // TestSyncScanCancelledMidWalkKeepsRecords is the regression net under
 // the post-walk guard. The scan is cancelled part-way through the
-// walk, so it reaches the guard holding a genuinely partial size
-// census and a still-populated index of records the walk never got to.
+// walk, so it reaches the guard having walked a genuinely partial tree
+// and holding a still-populated index of records the walk never got to.
 // Every one of those records would look vanished to the update phase.
 // The guard is what stops the scan there, and this test is what
 // notices if it stops doing so: deleting the guard, or making it
@@ -196,7 +197,7 @@ func TestSyncScanCancelledMidWalkKeepsRecords(t *testing.T) {
 	base := baselineGoroutines(t)
 
 	st, err := syncScan(newWalkClock(walkCancelAtDone), db,
-		[]string{dir}, walkCancelWorkers, false)
+		[]string{dir}, walkCancelWorkers, false, walkRules{})
 
 	assertWalkGuardAborted(t, st, err)
 	assertRecordsIntact(t, db, before)
@@ -208,10 +209,10 @@ func TestSyncScanCancelledMidWalkKeepsRecords(t *testing.T) {
 }
 
 // assertWalkGuardAborted checks that the scan stopped at the post-walk
-// guard: with a census that is neither empty (the walk really ran)
-// nor complete (it really was cut short), and with no record counted
-// for removal. A removal count means the partial census was carried
-// past the guard into the update phase, which is the failure this test
+// guard: with a walk that reached some files (it really ran) but not
+// all of them (it really was cut short), and with no record counted for
+// removal. A removal count means the partial walk was carried past
+// the guard into the update phase, which is the failure this test
 // exists to catch.
 func assertWalkGuardAborted(t *testing.T, st scanStats, err error) {
 	t.Helper()
@@ -222,30 +223,30 @@ func assertWalkGuardAborted(t *testing.T, st scanStats, err error) {
 	}
 
 	if st.unchanged == 0 {
-		t.Fatalf("stats = %+v: the census is empty, so the walk never "+
+		t.Fatalf("stats = %+v: the walk reached no file, so it never "+
 			"ran and the guard was reached for the wrong reason", st)
 	}
 
 	if st.unchanged >= walkCancelFiles {
-		t.Fatalf("stats = %+v: the census covers the whole tree, so the "+
-			"walk was not cut short", st)
+		t.Fatalf("stats = %+v: the walk reached the whole tree, so it "+
+			"was not cut short", st)
 	}
 
 	// The workers drop every directory still queued once the scan is
 	// cancelled, so only the files in the directories already in flight
-	// can add to the census after the fact. A census beyond that bound
+	// can still be reached after the fact. A walk beyond that bound
 	// would mean the cancellation was not observed where it should have
 	// been.
 	limit := walkCancelAtDone + walkCancelInFlightFiles
 	if st.unchanged > limit {
-		t.Errorf("census covers %d files, want at most %d: the walk kept "+
+		t.Errorf("the walk reached %d files, want at most %d: it kept "+
 			"taking directories off the queue after cancellation",
 			st.unchanged, limit)
 	}
 
 	if st.removed != 0 {
 		t.Errorf("stats = %+v: the scan counted records for removal from "+
-			"a partial census", st)
+			"a partial walk", st)
 	}
 }
 
@@ -268,7 +269,8 @@ func TestSyncScanCancelledBeforeLoadIndex(t *testing.T) {
 	ctx, cancel := context.WithCancel(t.Context())
 	cancel()
 
-	st, err := syncScan(ctx, db, []string{dir}, walkCancelWorkers, false)
+	st, err := syncScan(ctx, db, []string{dir}, walkCancelWorkers, false,
+		walkRules{})
 	if !errors.Is(err, context.Canceled) {
 		t.Fatalf("syncScan on a cancelled context = %v, want %v",
 			err, context.Canceled)
@@ -301,7 +303,7 @@ func TestSyncScanCancelledMidHashKeepsHashedRecords(t *testing.T) {
 	db := openTestDB(t)
 
 	st, err := syncScan(newWalkClock(hashCancelAtDone), db,
-		[]string{dir}, walkCancelWorkers, false)
+		[]string{dir}, walkCancelWorkers, false, walkRules{})
 	if !errors.Is(err, context.Canceled) {
 		t.Fatalf("syncScan cancelled mid-hash = %v, want %v",
 			err, context.Canceled)
@@ -356,7 +358,8 @@ func TestRunScanInterrupted(t *testing.T) {
 	stderr := captureStderr(t)
 	dir := buildSmokeTree(t)
 
-	err := runScan(t.Context(), []string{dir}, walkCancelWorkers, false)
+	err := runScan(t.Context(), []string{dir}, walkCancelWorkers, false,
+		false)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -380,7 +383,7 @@ func TestRunScanInterrupted(t *testing.T) {
 		defer close(done)
 
 		err = runScan(cancelledContext(t), []string{dir}, walkCancelWorkers,
-			false)
+			false, false)
 	}()
 
 	awaitReturn(t, done, "runScan")
@@ -407,7 +410,8 @@ func TestRunScanInterrupted(t *testing.T) {
 			got, before)
 	}
 
-	err = runScan(t.Context(), []string{dir}, walkCancelWorkers, false)
+	err = runScan(t.Context(), []string{dir}, walkCancelWorkers, false,
+		false)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -433,7 +437,7 @@ func TestRunScanInterruptedMidHash(t *testing.T) {
 	dir := buildWalkCancelTree(t)
 
 	err := runScan(newWalkClock(hashCancelAtDone), []string{dir},
-		walkCancelWorkers, false)
+		walkCancelWorkers, false, false)
 	if !errors.Is(err, errInterrupted) {
 		t.Fatalf("runScan interrupted mid-hash = %v, want %v",
 			err, errInterrupted)
@@ -617,7 +621,8 @@ func TestWalkOneDirStopsWhenCancelled(t *testing.T) {
 	// Unbuffered and unread: on a cancelled scan every send gives up.
 	events := make(chan walkEvent)
 
-	subs := walkOneDir(cancelledContext(t), dirJob{path: dir}, false, events)
+	subs := walkOneDir(cancelledContext(t), dirJob{path: dir}, false,
+		walkRules{}, events)
 	if len(subs) != 0 {
 		t.Errorf("cancelled walkOneDir returned %+v to descend into, "+
 			"want none", subs)
@@ -637,7 +642,8 @@ func TestWalkWorkersDropQueuedDirs(t *testing.T) {
 
 	missing := filepath.Join(t.TempDir(), "missing")
 
-	jobs, _, events := startWalkWorkers(cancelledContext(t), 2, false)
+	jobs, _, events := startWalkWorkers(cancelledContext(t), 2, false,
+		walkRules{})
 
 	for range 64 {
 		jobs <- dirJob{path: missing}
@@ -668,7 +674,7 @@ func TestWalkWorkerAbandonsSubdirHandoff(t *testing.T) {
 	ctx, cancel := context.WithCancel(t.Context())
 	defer cancel()
 
-	jobs, subdirs, events := startWalkWorkers(ctx, 1, false)
+	jobs, subdirs, events := startWalkWorkers(ctx, 1, false, walkRules{})
 
 	// Fill the hand-back channel to its capacity — one slot per worker
 	// — so the worker's own hand-back is certain to block.
@@ -757,7 +763,9 @@ func TestHashWorkerDropsQueuedRuns(t *testing.T) {
 
 	var hashed atomic.Bool
 
-	hash := func(path string, size int64) (string, string, string, error) {
+	hash := func(path string, size int64) (
+		[sha256.Size]byte, [sha256.Size]byte, [sha256.Size]byte, error,
+	) {
 		hashed.Store(true)
 
 		return hashSignature(path, size)
@@ -797,7 +805,9 @@ func TestHashWorkerAbandonsBlockedSend(t *testing.T) {
 
 	// The scan is cancelled while the worker hashes, so the worker has
 	// already passed the check that drops queued runs.
-	hash := func(path string, size int64) (string, string, string, error) {
+	hash := func(path string, size int64) (
+		[sha256.Size]byte, [sha256.Size]byte, [sha256.Size]byte, error,
+	) {
 		cancel()
 
 		return hashSignature(path, size)

db.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"crypto/sha256"
 	"database/sql"
 	"errors"
 	"fmt"
@@ -48,16 +49,17 @@ const lockFilePerm = 0o600
 // createTableSQL is the schema applied to a fresh database. Paths are
 // BLOBs because Unix paths are raw bytes, not guaranteed UTF-8. mtime
 // holds whole Unix seconds and mtime_nsec the nanoseconds within that
-// second.
+// second. head, tail and content each hold the raw 32 bytes of a
+// SHA-256.
 const createTableSQL = `
 CREATE TABLE files (
     path       BLOB PRIMARY KEY,
     size       INTEGER NOT NULL,
     mtime      INTEGER NOT NULL,
     mtime_nsec INTEGER NOT NULL,
-    head       TEXT NOT NULL,
-    tail       TEXT NOT NULL,
-    content    TEXT NOT NULL
+    head       BLOB NOT NULL,
+    tail       BLOB NOT NULL,
+    content    BLOB NOT NULL
 ) WITHOUT ROWID
 `
 
@@ -92,6 +94,10 @@ var errSchemaVersion = errors.New("unsupported database schema version")
 // database.
 var errScanRunning = errors.New("another scan is running")
 
+// errHashSize reports a record whose head, tail or content is not the
+// 32 bytes of a SHA-256.
+var errHashSize = errors.New("hash is not 32 bytes")
+
 // databasePath resolves the database location: SFDUPES_DATABASE when
 // set and non-empty, the compiled-in default otherwise. It returns the
 // path, with the working directory, its symlinks resolved, put in front
@@ -109,10 +115,8 @@ func databasePath() (string, string, error) {
 	}
 
 	// The working directory as the kernel reports it, with no symlink
-	// in it. os.Getwd may return PWD instead, which can name it through
-	// a symlink; a ".." after that symlink then leads somewhere else
-	// once the path is cleaned, as scan cleans it to create the
-	// database's directory.
+	// in it, as README "Database" says. os.Getwd may return PWD
+	// instead, which can name it through a symlink.
 	wd, err := unix.Getwd()
 	if err != nil {
 		return "", "", fmt.Errorf("resolve database path %s: %w", path, err)
@@ -125,6 +129,24 @@ func databasePath() (string, string, error) {
 	return strings.TrimSuffix(wd, "/") + "/" + path, source, nil
 }
 
+// createDatabaseDirectory creates the directory the database at path
+// goes in, and any directory above it, if missing. path is absolute, as
+// databasePath returns it. The directory is path with its last element
+// cut off as text, by filepath.Split. filepath.Dir would clean it,
+// dropping each ".." together with the directory name before it; when
+// that name is a symlink, the cleaned path names another directory than
+// the one the system reaches when it opens path.
+func createDatabaseDirectory(path string) error {
+	dir, _ := filepath.Split(path)
+
+	err := os.MkdirAll(dir, dbDirPerm)
+	if err != nil {
+		return fmt.Errorf("create database directory: %w", err)
+	}
+
+	return nil
+}
+
 // scanParams are the connection parameters for scan: read-write, with
 // WAL journaling and a busy timeout, so a report can run while a cron
 // scan is in progress. closeScanDatabase leaves WAL mode again.
@@ -179,9 +201,9 @@ func openDB(path, params string) (*sql.DB, error) {
 // that deleted it would let the next scan lock a new file while
 // another still holds the old one.
 func lockScanDatabase(path string) (*os.File, error) {
-	err := os.MkdirAll(filepath.Dir(path), dbDirPerm)
+	err := createDatabaseDirectory(path)
 	if err != nil {
-		return nil, fmt.Errorf("create database directory: %w", err)
+		return nil, err
 	}
 
 	// Like SQLite, this follows a symlink at path and creates its
@@ -225,9 +247,9 @@ func lockScanDatabase(path string) (*os.File, error) {
 // openScanDatabase opens the database for the scan subcommand, creating
 // the file, its parent directory, and the schema as needed.
 func openScanDatabase(ctx context.Context, path string) (*sql.DB, error) {
-	err := os.MkdirAll(filepath.Dir(path), dbDirPerm)
+	err := createDatabaseDirectory(path)
 	if err != nil {
-		return nil, fmt.Errorf("create database directory: %w", err)
+		return nil, err
 	}
 
 	db, err := openDB(path, scanParams)
@@ -245,6 +267,42 @@ func openScanDatabase(ctx context.Context, path string) (*sql.DB, error) {
 	return db, nil
 }
 
+// databaseFiles returns, by device and inode, the files of the database
+// at path that the scan keeps open: the database file, its -wal and
+// -shm files and its .lock file, each named from the database's path
+// with symlinks resolved, as SQLite and lockScanDatabase name them. The
+// scan calls it once the database and the lock file are open, so that
+// its walk passes over them however it reaches them, through a
+// symlinked directory included. A file that does not exist then is left
+// out, since no walk can reach it. There is no -journal file while the
+// database is in WAL mode.
+func databaseFiles(path string) ([]fileRec, error) {
+	resolved, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		return nil, fmt.Errorf("resolve database path: %w", err)
+	}
+
+	var files []fileRec
+
+	for _, p := range []string{
+		resolved, resolved + "-wal", resolved + "-shm", resolved + ".lock",
+	} {
+		fi, err := os.Lstat(p)
+		if errors.Is(err, fs.ErrNotExist) {
+			continue
+		}
+
+		if err != nil {
+			return nil, fmt.Errorf("database: %w", err)
+		}
+
+		dev, ino := inodeOfInfo(fi)
+		files = append(files, fileRec{path: p, dev: dev, ino: ino})
+	}
+
+	return files, nil
+}
+
 // closeScanDatabase switches the database at path from WAL back to
 // rollback-journal mode and closes it. Out of WAL mode the database
 // file alone holds the whole database, so a reader needs no -wal or
@@ -440,19 +498,24 @@ func loadFileRows(ctx context.Context, db *sql.DB, total func(n int64),
 
 	for rows.Next() {
 		var (
-			path      []byte
-			sec, nsec int64
-			r         scanRec
+			path, head, tail, content []byte
+			sec, nsec                 int64
+			r                         scanRec
 		)
 
-		err = rows.Scan(&path, &r.size, &sec, &nsec, &r.head, &r.tail,
-			&r.content)
+		err = rows.Scan(&path, &r.size, &sec, &nsec, &head, &tail, &content)
 		if err != nil {
 			return fmt.Errorf("read record: %w", err)
 		}
 
 		r.path = string(path)
 		r.mtime = time.Unix(sec, nsec)
+
+		err = r.setHashes(head, tail, content)
+		if err != nil {
+			return fmt.Errorf("read record %s: %w", escapePath(r.path), err)
+		}
+
 		fn(r)
 	}
 
@@ -509,17 +572,22 @@ func loadSignatureRows(ctx context.Context, db *sql.DB,
 
 	for rows.Next() {
 		var (
-			path []byte
-			r    scanRec
+			path, head, tail, content []byte
+			r                         scanRec
 		)
 
-		err = rows.Scan(&r.size, &r.head, &r.tail, &r.content, &path)
+		err = rows.Scan(&r.size, &head, &tail, &content, &path)
 		if err != nil {
 			return fmt.Errorf("read record: %w", err)
 		}
 
 		r.path = string(path)
 
+		err = r.setHashes(head, tail, content)
+		if err != nil {
+			return fmt.Errorf("read record %s: %w", escapePath(r.path), err)
+		}
+
 		err = fn(r)
 		if err != nil {
 			return err
@@ -534,6 +602,22 @@ func loadSignatureRows(ctx context.Context, db *sql.DB,
 	return nil
 }
 
+// setHashes sets r's head, tail and content to the values read from
+// those columns. Each must be the raw 32 bytes of a SHA-256.
+func (r *scanRec) setHashes(head, tail, content []byte) error {
+	for _, b := range [][]byte{head, tail, content} {
+		if len(b) != sha256.Size {
+			return fmt.Errorf("%w: found %d bytes", errHashSize, len(b))
+		}
+	}
+
+	r.head = [sha256.Size]byte(head)
+	r.tail = [sha256.Size]byte(tail)
+	r.content = [sha256.Size]byte(content)
+
+	return nil
+}
+
 // countRecords returns the number of records in the database.
 func countRecords(ctx context.Context, db *sql.DB) (int64, error) {
 	var n int64
@@ -546,15 +630,11 @@ func countRecords(ctx context.Context, db *sql.DB) (int64, error) {
 	return n, nil
 }
 
-// databaseCountsSQL counts the records, those with head and tail
-// hashes and those with a content hash, and adds up their sizes, in one
+// databaseCountsSQL counts the records and adds up their sizes, in one
 // pass over the table. A SUM over no rows is NULL, so on an empty table
-// each SUM falls back to 0.
+// the SUM falls back to 0.
 const databaseCountsSQL = `
-SELECT COUNT(*),
-       COALESCE(SUM(head <> '' AND tail <> ''), 0),
-       COALESCE(SUM(content <> ''), 0),
-       COALESCE(SUM(size), 0)
+SELECT COUNT(*), COALESCE(SUM(size), 0)
 FROM files
 `
 
@@ -563,8 +643,6 @@ FROM files
 type databaseCounts struct {
 	schemaVersion int
 	records       int64 // every record
-	headTail      int64 // records with head and tail hashes
-	content       int64 // records with a content hash
 	size          int64 // the sizes of all records added up
 }
 
@@ -592,7 +670,7 @@ func readDatabaseCounts(ctx context.Context,
 	}
 
 	err = tx.QueryRowContext(ctx, databaseCountsSQL).
-		Scan(&c.records, &c.headTail, &c.content, &c.size)
+		Scan(&c.records, &c.size)
 	if err != nil {
 		return c, fmt.Errorf("count records: %w", err)
 	}
@@ -600,15 +678,15 @@ func readDatabaseCounts(ctx context.Context,
 	return c, nil
 }
 
-// loadFileMeta streams every record's path, size, mtime, and whether
-// it carries hashes to fn. Scan change detection needs no hash
-// values, and skipping the hash columns keeps the scan's in-memory
-// index small on multi-million-file databases.
+// loadFileMeta streams every record's path, size and mtime to fn. Scan
+// change detection needs no hash values, and skipping the hash columns
+// keeps the scan's in-memory index small on multi-million-file
+// databases.
 func loadFileMeta(ctx context.Context, db *sql.DB,
-	fn func(path string, size int64, mtime time.Time, hashed bool),
+	fn func(path string, size int64, mtime time.Time),
 ) error {
 	rows, err := db.QueryContext(ctx,
-		"SELECT path, size, mtime, mtime_nsec, head <> '' FROM files")
+		"SELECT path, size, mtime, mtime_nsec FROM files")
 	if err != nil {
 		return fmt.Errorf("read records: %w", err)
 	}
@@ -619,94 +697,14 @@ func loadFileMeta(ctx context.Context, db *sql.DB,
 		var (
 			path            []byte
 			size, sec, nsec int64
-			hashed          int64
 		)
 
-		err = rows.Scan(&path, &size, &sec, &nsec, &hashed)
+		err = rows.Scan(&path, &size, &sec, &nsec)
 		if err != nil {
 			return fmt.Errorf("read record: %w", err)
 		}
 
-		fn(string(path), size, time.Unix(sec, nsec), hashed != 0)
-	}
-
-	err = rows.Err()
-	if err != nil {
-		return fmt.Errorf("read records: %w", err)
-	}
-
-	return nil
-}
-
-// contentGroupsSQL selects each group (the records sharing a size,
-// head, and tail) of records of at least headTailMin bytes that has more
-// than one record and at least one record without a content hash, with
-// the number of its records.
-const contentGroupsSQL = `
-SELECT size, head, tail, COUNT(*) AS records
-FROM files
-WHERE size >= ? AND head <> ''
-GROUP BY size, head, tail
-HAVING COUNT(*) > 1 AND SUM(content = '') > 0
-`
-
-// contentCandidatesSQL selects every record of the groups
-// contentGroupsSQL selects, with whether each record has a content
-// hash. SQLite does the grouping, so no other record's hashes are
-// loaded into memory; the rows come ordered by size, head, and tail, so
-// each group's rows arrive together.
-const contentCandidatesSQL = `
-SELECT f.path, f.size, f.mtime, f.mtime_nsec, f.head, f.tail, f.content <> ''
-FROM files AS f
-JOIN (` + contentGroupsSQL + `) AS g USING (size, head, tail)
-ORDER BY size, head, tail
-`
-
-// countContentCandidates returns the number of rows of
-// contentCandidatesSQL, adding up the records of the groups
-// contentGroupsSQL selects, so it neither joins nor sorts.
-func countContentCandidates(ctx context.Context, db *sql.DB) (int64, error) {
-	var n int64
-
-	err := db.QueryRowContext(ctx,
-		"SELECT COALESCE(SUM(records), 0) FROM ("+contentGroupsSQL+")",
-		headTailMin).Scan(&n)
-	if err != nil {
-		return 0, fmt.Errorf("count content candidates: %w", err)
-	}
-
-	return n, nil
-}
-
-// loadContentCandidates streams the rows of contentCandidatesSQL to fn:
-// each record, without its content hash, and whether it has one.
-func loadContentCandidates(ctx context.Context, db *sql.DB,
-	fn func(r scanRec, hashed bool),
-) error {
-	rows, err := db.QueryContext(ctx, contentCandidatesSQL, headTailMin)
-	if err != nil {
-		return fmt.Errorf("read records: %w", err)
-	}
-
-	defer func() { _ = rows.Close() }()
-
-	for rows.Next() {
-		var (
-			path      []byte
-			sec, nsec int64
-			r         scanRec
-			hashed    int64
-		)
-
-		err = rows.Scan(&path, &r.size, &sec, &nsec, &r.head, &r.tail,
-			&hashed)
-		if err != nil {
-			return fmt.Errorf("read record: %w", err)
-		}
-
-		r.path = string(path)
-		r.mtime = time.Unix(sec, nsec)
-		fn(r, hashed != 0)
+		fn(string(path), size, time.Unix(sec, nsec))
 	}
 
 	err = rows.Err()
@@ -790,7 +788,8 @@ func execUpserts(ctx context.Context, tx *sql.Tx, upserts []scanRec,
 
 	for _, r := range upserts {
 		_, err = st.ExecContext(ctx, []byte(r.path), r.size,
-			r.mtime.Unix(), r.mtime.Nanosecond(), r.head, r.tail, r.content)
+			r.mtime.Unix(), r.mtime.Nanosecond(),
+			r.head[:], r.tail[:], r.content[:])
 		if err != nil {
 			return fmt.Errorf("upsert %s: %w", r.path, err)
 		}

db_test.go

@@ -2,9 +2,11 @@ package main
 
 import (
 	"context"
+	"crypto/sha256"
 	"database/sql"
 	"errors"
 	"fmt"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"slices"
@@ -118,6 +120,116 @@ func TestOpenScanDatabaseCreates(t *testing.T) {
 	}
 }
 
+// TestScanCreatesDatabaseDirectoryAfterSymlink has a database path go
+// through a symlink to a directory, then "..", to a missing directory.
+// With srv/link a symlink to data/x, srv/link/../new/db.sqlite leads to
+// data/new/db.sqlite. lockScanDatabase and openScanDatabase, the two
+// places scan creates the database's directory, must each create the
+// database there, and nothing at srv/new, where the path leads once
+// cleaned as text.
+func TestScanCreatesDatabaseDirectoryAfterSymlink(t *testing.T) {
+	t.Parallel()
+
+	creates := map[string]func(ctx context.Context, path string) error{
+		"lockScanDatabase": func(_ context.Context, path string) error {
+			lock, err := lockScanDatabase(path)
+			if err == nil {
+				_ = lock.Close()
+			}
+
+			return err
+		},
+		"openScanDatabase": func(ctx context.Context, path string) error {
+			db, err := openScanDatabase(ctx, path)
+			if err == nil {
+				_ = db.Close()
+			}
+
+			return err
+		},
+	}
+
+	for name, create := range creates {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			dir, err := filepath.EvalSymlinks(t.TempDir())
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = os.MkdirAll(filepath.Join(dir, "data", "x"), 0o750)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = os.Mkdir(filepath.Join(dir, "srv"), 0o750)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = os.Symlink(filepath.Join(dir, "data", "x"),
+				filepath.Join(dir, "srv", "link"))
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = create(t.Context(), dir+"/srv/link/../new/db.sqlite")
+			if err != nil {
+				t.Fatalf("%s: %v", name, err)
+			}
+
+			_, err = os.Stat(filepath.Join(dir, "data", "new", "db.sqlite"))
+			if err != nil {
+				t.Errorf("database the path leads to: %v", err)
+			}
+
+			_, err = os.Lstat(filepath.Join(dir, "srv", "new"))
+			if !errors.Is(err, fs.ErrNotExist) {
+				t.Errorf("srv/new: stat error %v, want it missing", err)
+			}
+		})
+	}
+}
+
+// TestDatabaseFiles opens a database through a symlink to its file:
+// databaseFiles finds the database file and its -wal and -shm files
+// beside the symlink's target, where SQLite keeps them, and leaves out
+// the .lock file, which only a scan creates.
+func TestDatabaseFiles(t *testing.T) {
+	t.Parallel()
+
+	path := testDBPath(t)
+	link := filepath.Join(t.TempDir(), "link.sqlite")
+
+	err := os.Symlink(path, link)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	db, err := openScanDatabase(t.Context(), link)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	files, err := databaseFiles(link)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got := make([]string, 0, len(files))
+	for _, f := range files {
+		got = append(got, f.path)
+	}
+
+	want := []string{path, path + "-wal", path + "-shm"}
+	if !slices.Equal(got, want) {
+		t.Errorf("databaseFiles(%s) = %q, want %q", link, got, want)
+	}
+}
+
 func TestOpenDatabaseUnversionedForeign(t *testing.T) {
 	t.Parallel()
 
@@ -362,6 +474,67 @@ func TestLoadRowsCountAgreeDuringScan(t *testing.T) {
 	}
 }
 
+// TestLoadRowsRefuseWrongSizeHash stores a record whose head, tail or
+// content is not the 32 bytes of a SHA-256: either one byte, or the 64
+// bytes of a SHA-256 written as hex text. loadFileRows and
+// loadSignatureRows must each fail on it with an error naming its path.
+func TestLoadRowsRefuseWrongSizeHash(t *testing.T) {
+	t.Parallel()
+
+	hexText := strings.Repeat("ab", sha256.Size)
+
+	cases := []struct {
+		name   string
+		update string
+		value  any
+	}{
+		{"one-byte head", "UPDATE files SET head = ?", []byte{0}},
+		{"hex-text head", "UPDATE files SET head = ?", hexText},
+		{"one-byte tail", "UPDATE files SET tail = ?", []byte{0}},
+		{"hex-text tail", "UPDATE files SET tail = ?", hexText},
+		{"one-byte content", "UPDATE files SET content = ?", []byte{0}},
+		{"hex-text content", "UPDATE files SET content = ?", hexText},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+
+			db := openTestDB(t)
+
+			err := applyChanges(t.Context(), db,
+				[]scanRec{{path: "/a/f"}}, nil, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			_, err = db.ExecContext(t.Context(), c.update, c.value)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			loads := map[string]func() error{
+				"loadFileRows": func() error {
+					return loadFileRows(t.Context(), db, func(int64) {},
+						func(scanRec) {})
+				},
+				"loadSignatureRows": func() error {
+					return loadSignatureRows(t.Context(), db, func(int64) {},
+						func(scanRec) error { return nil })
+				},
+			}
+
+			for name, load := range loads {
+				err := load()
+				if !errors.Is(err, errHashSize) ||
+					!strings.Contains(err.Error(), "/a/f") {
+					t.Errorf("%s: err = %v, want %v naming /a/f",
+						name, err, errHashSize)
+				}
+			}
+		})
+	}
+}
+
 // TestSignatureRowsNeedNoSort checks that SQLite reads signatureRowsSQL
 // from the files_signature index alone, with nothing to sort: the
 // first record comes at once, so report's read phase counts each
@@ -416,12 +589,13 @@ func TestApplyChangesRoundTrip(t *testing.T) {
 	// written.
 	recs := []scanRec{
 		{
-			size: 2, mtime: time.Unix(20, 999_999_999), head: "h2", tail: "t2",
-			content: "c2", path: "/a/tab\tnew\nline",
+			size: 2, mtime: time.Unix(20, 999_999_999), head: testHash("h2"),
+			tail: testHash("t2"), content: testHash("c2"),
+			path: "/a/tab\tnew\nline",
 		},
 		{
-			size: 1, mtime: time.Unix(10, 0), head: "h1", tail: "t1",
-			content: "c1", path: "/a/x",
+			size: 1, mtime: time.Unix(10, 0), head: testHash("h1"),
+			tail: testHash("t1"), content: testHash("c1"), path: "/a/x",
 		},
 	}
 
@@ -442,8 +616,8 @@ func TestApplyChangesRoundTrip(t *testing.T) {
 	// An upsert for an existing path updates in place; a delete
 	// removes exactly its path.
 	upd := scanRec{
-		size: 3, mtime: time.Unix(30, 0), head: "h3", tail: "t3", content: "c3",
-		path: "/a/x",
+		size: 3, mtime: time.Unix(30, 0), head: testHash("h3"),
+		tail: testHash("t3"), content: testHash("c3"), path: "/a/x",
 	}
 
 	err = applyChanges(t.Context(), db, []scanRec{upd},
@@ -470,8 +644,8 @@ func TestApplyChangesBatching(t *testing.T) {
 	recs := make([]scanRec, 0, n)
 	for i := range n {
 		recs = append(recs, scanRec{
-			size: int64(i), mtime: time.Unix(1, 0), head: "h", tail: "t",
-			path: fmt.Sprintf("/batch/%07d", i),
+			size: int64(i), mtime: time.Unix(1, 0), head: testHash("h"),
+			tail: testHash("t"), path: fmt.Sprintf("/batch/%07d", i),
 		})
 	}
 
@@ -501,62 +675,3 @@ func TestApplyChangesBatching(t *testing.T) {
 		t.Fatalf("records = %d, want 0", len(got))
 	}
 }
-
-// TestCountContentCandidates checks that countContentCandidates counts
-// the records the content phase's search returns: those of each group
-// of two or more records of headTailMin or more with a head, where at
-// least one has no content hash.
-func TestCountContentCandidates(t *testing.T) {
-	t.Parallel()
-
-	db := openTestDB(t)
-
-	// Each group's records: size, head, and content, one per record.
-	groups := []struct {
-		size     int64
-		head     string
-		contents []string
-	}{
-		{headTailMin, "h", []string{"", "c", "c"}}, // returned
-		{headTailMin + 1, "h", []string{"", ""}},   // returned
-		{headTailMin + 2, "h", []string{"c", "c"}}, // all hashed
-		{headTailMin + 3, "h", []string{""}},       // one record
-		{headTailMin - 1, "h", []string{"", ""}},   // too small
-		{headTailMin + 4, "", []string{"", ""}},    // no head
-	}
-
-	var recs []scanRec
-
-	for _, g := range groups {
-		for _, content := range g.contents {
-			recs = append(recs, scanRec{
-				size: g.size, mtime: time.Unix(1, 0), head: g.head,
-				tail: "t", content: content,
-				path: fmt.Sprintf("/r/%d", len(recs)),
-			})
-		}
-	}
-
-	err := applyChanges(t.Context(), db, recs, nil, nil)
-	if err != nil {
-		t.Fatalf("applyChanges: %v", err)
-	}
-
-	got, err := countContentCandidates(t.Context(), db)
-	if err != nil {
-		t.Fatalf("countContentCandidates: %v", err)
-	}
-
-	var returned int64
-
-	err = loadContentCandidates(t.Context(), db,
-		func(scanRec, bool) { returned++ })
-	if err != nil {
-		t.Fatalf("loadContentCandidates: %v", err)
-	}
-
-	if got != 5 || returned != 5 {
-		t.Errorf("count = %d, records returned = %d, want 5 and 5",
-			got, returned)
-	}
-}

exclude.go

@@ -0,0 +1,195 @@
+package main
+
+// This file holds two rules for the walk (README "Rules for the walk"):
+// the default excludes, the paths a scan's walk does not enter below an
+// operand unless scan is given --no-default-excludes, and the
+// filesystems that are not persistent, on which the scan never records
+// or reads anything.
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"path/filepath"
+	"slices"
+	"strings"
+
+	"golang.org/x/sys/unix"
+)
+
+// The systems that have default excludes, as runtime.GOOS names them.
+const (
+	goosLinux   = "linux"
+	goosDarwin  = "darwin"
+	goosWindows = "windows"
+)
+
+// The fields of a line of mountInfoPath that readMountInfo reads,
+// counted from 0 (see proc(5)): the device ID, as major:minor, is the
+// third field, and after the sixth come optional fields, then a field
+// holding "-", then the filesystem type.
+const (
+	deviceField         = 2
+	optionalFieldsStart = 6
+)
+
+// typesPerHelpLine is how many filesystem types the scan command's help
+// lists on each line.
+const typesPerHelpLine = 6
+
+// errMountInfoLine reports a line of mountInfoPath without the fields
+// readMountInfo reads.
+var errMountInfoLine = errors.New("unexpected line")
+
+// walkRules holds the rules for the walk that a scan sets up as it
+// starts. excludes are the default excludes, or none with
+// --no-default-excludes. nonPersistent maps the device ID of every
+// mounted filesystem that is not persistent to its type; the scan
+// records and reads nothing on one of those, whatever the flags.
+// databaseFiles are the scan's own database files, which the walk
+// passes over (see databaseFiles in db.go).
+type walkRules struct {
+	excludes      []string
+	nonPersistent map[uint64]string
+	databaseFiles []fileRec
+}
+
+// defaultExcludes returns the default excludes of the system goos
+// names, as runtime.GOOS does: a fixed list on Linux, macOS and
+// Windows, and none on any other system.
+func defaultExcludes(goos string) []string {
+	switch goos {
+	case goosLinux:
+		return []string{"/proc", "/sys", "/dev", "/run", "/tmp", "/var/tmp"}
+	case goosDarwin:
+		// A walk of / reaches everything in /System/Volumes/Data through
+		// the firmlinks, so walking it as well would record each of
+		// those files twice.
+		return []string{
+			"/dev", "/private/tmp", "/private/var/tmp", "/private/var/vm",
+			"/System/Volumes/VM", "/System/Volumes/Data",
+		}
+	case goosWindows:
+		// Relative to the root of the drive an operand lies on. The
+		// first three are the page, swap and hibernation files.
+		return []string{
+			"pagefile.sys", "swapfile.sys", "hiberfil.sys",
+			"System Volume Information", "$Recycle.Bin", `Windows\Temp`,
+			`Users\*\AppData\Local\Temp`,
+		}
+	default:
+		return nil
+	}
+}
+
+// isDefaultExclude reports whether path is one of excludes, in which a
+// * matches one path component.
+func isDefaultExclude(path string, excludes []string) bool {
+	for _, pattern := range excludes {
+		// The patterns are fixed, so none is malformed.
+		if ok, _ := filepath.Match(pattern, path); ok {
+			return true
+		}
+	}
+
+	return false
+}
+
+// nonPersistentFilesystemTypes returns the filesystem types that are
+// not persistent: filesystems that the kernel makes up or that are kept
+// in memory. devfs is the macOS filesystem of /dev; the others are
+// Linux names.
+func nonPersistentFilesystemTypes() []string {
+	return []string{
+		"proc", "sysfs", "devtmpfs", "devpts", "tmpfs", "ramfs",
+		"cgroup", "cgroup2", "debugfs", "tracefs", "securityfs", "pstore",
+		"bpf", "configfs", "fusectl", "mqueue", "hugetlbfs", "efivarfs",
+		"binfmt_misc", "autofs", "nsfs", "rpc_pipefs", "selinuxfs", "devfs",
+	}
+}
+
+// nonPersistentLine returns the line the scan prints for path when fi,
+// its lstat, puts it on a filesystem in rules.nonPersistent, and ""
+// when it is on any other.
+func (rules walkRules) nonPersistentLine(path string, fi fs.FileInfo) string {
+	dev, ok := deviceOfInfo(fi)
+	if !ok {
+		return ""
+	}
+
+	fsType, found := rules.nonPersistent[dev]
+	if !found {
+		return ""
+	}
+
+	return fmt.Sprintf("scan: skipped %s (%s, not a persistent filesystem)",
+		path, fsType)
+}
+
+// readMountInfo reads mountinfo, laid out as mountInfoPath is, and
+// returns the device ID of every mounted filesystem that is not
+// persistent, with its type. The device ID is the one each line gives,
+// not that of the file now at its mount point, so a mount that a later
+// mount hides never adds the device of another filesystem.
+func readMountInfo(mountinfo io.Reader) (map[uint64]string, error) {
+	types := nonPersistentFilesystemTypes()
+	devices := make(map[uint64]string)
+	lines := bufio.NewScanner(mountinfo)
+
+	for lines.Scan() {
+		fields := strings.Fields(lines.Text())
+
+		sep := slices.Index(fields, "-")
+		if sep < optionalFieldsStart || sep+1 >= len(fields) {
+			return nil, fmt.Errorf("%w: %q", errMountInfoLine, lines.Text())
+		}
+
+		var major, minor uint32
+
+		_, err := fmt.Sscanf(fields[deviceField], "%d:%d", &major, &minor)
+		if err != nil {
+			return nil, fmt.Errorf("%w: %q", errMountInfoLine, lines.Text())
+		}
+
+		fsType := fields[sep+1]
+		if slices.Contains(types, fsType) {
+			devices[unix.Mkdev(major, minor)] = fsType
+		}
+	}
+
+	return devices, lines.Err()
+}
+
+// defaultExcludesHelp describes, for the scan command's help, the
+// default excludes of the system goos names and, where the scan lists
+// the mounted filesystems, the types it never records anything on.
+func defaultExcludesHelp(goos string) string {
+	var help strings.Builder
+
+	dirs := defaultExcludes(goos)
+	if len(dirs) == 0 {
+		help.WriteString("This system has no default excludes.\n")
+	} else {
+		help.WriteString("Below an operand, the walk does not enter these " +
+			"default excludes, unless\n--no-default-excludes is given:\n\n")
+
+		for _, dir := range dirs {
+			fmt.Fprintf(&help, "  %s\n", dir)
+		}
+	}
+
+	if goos == goosLinux || goos == goosDarwin {
+		help.WriteString("\nWith or without --no-default-excludes, the scan " +
+			"records nothing on a\nfilesystem that is not persistent, " +
+			"one of these types:\n\n")
+
+		types := nonPersistentFilesystemTypes()
+		for line := range slices.Chunk(types, typesPerHelpLine) {
+			fmt.Fprintf(&help, "  %s\n", strings.Join(line, ", "))
+		}
+	}
+
+	return help.String()
+}

exclude_darwin.go

@@ -0,0 +1,52 @@
+//go:build darwin
+
+package main
+
+import (
+	"slices"
+
+	"golang.org/x/sys/unix"
+)
+
+// nonPersistentFilesystems returns the device ID of every mounted
+// filesystem that is not persistent, with its type, from the system's
+// list of mounted filesystems. The device ID is read with lstat on the
+// mount point. Where one filesystem is mounted over another on the same
+// mount point, the later one in the list counts. A mount point that
+// lstat cannot reach is left out.
+func nonPersistentFilesystems() (map[uint64]string, error) {
+	// The first call counts the filesystems, the second lists them.
+	n, err := unix.Getfsstat(nil, unix.MNT_NOWAIT)
+	if err != nil {
+		return nil, err
+	}
+
+	list := make([]unix.Statfs_t, n)
+
+	n, err = unix.Getfsstat(list, unix.MNT_NOWAIT)
+	if err != nil {
+		return nil, err
+	}
+
+	mounts := make(map[string]string, n)
+
+	for _, st := range list[:n] {
+		mounts[unix.ByteSliceToString(st.Mntonname[:])] =
+			unix.ByteSliceToString(st.Fstypename[:])
+	}
+
+	types := nonPersistentFilesystemTypes()
+	devices := make(map[uint64]string)
+
+	for mountPoint, fsType := range mounts {
+		if !slices.Contains(types, fsType) {
+			continue
+		}
+
+		if dev, ok := deviceOfPath(mountPoint); ok {
+			devices[dev] = fsType
+		}
+	}
+
+	return devices, nil
+}

exclude_other.go

@@ -0,0 +1,36 @@
+//go:build !darwin
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"runtime"
+)
+
+// mountInfoPath is the file in which Linux lists the mounts the reading
+// process sees.
+const mountInfoPath = "/proc/self/mountinfo"
+
+// nonPersistentFilesystems returns the device ID of every mounted
+// filesystem that is not persistent, with its type: on Linux read from
+// mountInfoPath (see readMountInfo), and on any other system none.
+func nonPersistentFilesystems() (map[uint64]string, error) {
+	if runtime.GOOS != goosLinux {
+		return map[uint64]string{}, nil
+	}
+
+	f, err := os.Open(mountInfoPath)
+	if err != nil {
+		return nil, err
+	}
+
+	defer func() { _ = f.Close() }()
+
+	devices, err := readMountInfo(f)
+	if err != nil {
+		return nil, fmt.Errorf("read %s: %w", mountInfoPath, err)
+	}
+
+	return devices, nil
+}

exclude_test.go

@@ -0,0 +1,513 @@
+package main
+
+import (
+	"bytes"
+	"errors"
+	"maps"
+	"os"
+	"path/filepath"
+	"runtime"
+	"slices"
+	"strings"
+	"testing"
+
+	"golang.org/x/sys/unix"
+)
+
+func TestDefaultExcludes(t *testing.T) {
+	t.Parallel()
+
+	// README "Rules for the walk": each system's list.
+	cases := map[string][]string{
+		goosLinux: {"/proc", "/sys", "/dev", "/run", "/tmp", "/var/tmp"},
+		goosDarwin: {
+			"/dev", "/private/tmp", "/private/var/tmp", "/private/var/vm",
+			"/System/Volumes/VM", "/System/Volumes/Data",
+		},
+		goosWindows: {
+			"pagefile.sys", "swapfile.sys", "hiberfil.sys",
+			"System Volume Information", "$Recycle.Bin", `Windows\Temp`,
+			`Users\*\AppData\Local\Temp`,
+		},
+		"freebsd": nil,
+	}
+
+	for goos, want := range cases {
+		if got := defaultExcludes(goos); !slices.Equal(got, want) {
+			t.Errorf("defaultExcludes(%q) = %q, want %q", goos, got, want)
+		}
+	}
+}
+
+func TestIsDefaultExclude(t *testing.T) {
+	t.Parallel()
+
+	// A * matches one path component, no more and no fewer.
+	excludes := []string{"/scratch", "/home/*/cache"}
+
+	cases := map[string]bool{
+		"/scratch":        true,
+		"/scratch/x":      false,
+		"/home/u/cache":   true,
+		"/home/u/v/cache": false,
+		"/home/cache":     false,
+	}
+
+	for path, want := range cases {
+		if got := isDefaultExclude(path, excludes); got != want {
+			t.Errorf("isDefaultExclude(%q) = %v, want %v", path, got, want)
+		}
+	}
+}
+
+func TestReadMountInfo(t *testing.T) {
+	t.Parallel()
+
+	// The second-to-last line has no optional fields. The tmpfs on
+	// /data/a/b is hidden by the root filesystem's /srv, mounted over
+	// /data/a after it: the tmpfs still gives its own device, and the
+	// root filesystem's device is not listed.
+	mountinfo := strings.Join([]string{
+		"22 1 8:1 / / rw,relatime shared:1 - ext4 /dev/sda1 rw",
+		"23 22 0:21 / /proc rw,nosuid shared:12 - proc none rw",
+		"24 22 0:22 / /sys rw,nosuid shared:7 - sysfs none rw",
+		"25 22 0:23 / /data/a/b rw shared:2 - tmpfs none rw",
+		"26 22 8:1 /srv /data/a rw - ext4 /dev/sda1 rw",
+		"27 22 0:25 / /srv/auto rw shared:4 - autofs systemd-1 rw",
+	}, "\n")
+
+	got, err := readMountInfo(strings.NewReader(mountinfo))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	want := map[uint64]string{
+		unix.Mkdev(0, 21): "proc", unix.Mkdev(0, 22): "sysfs",
+		unix.Mkdev(0, 23): "tmpfs", unix.Mkdev(0, 25): "autofs",
+	}
+	if !maps.Equal(got, want) {
+		t.Errorf("readMountInfo = %v, want %v", got, want)
+	}
+
+	for _, line := range []string{
+		"22 1 8:1 / / rw,relatime\n",
+		"22 1 sda / / rw,relatime shared:1 - ext4 /dev/sda1 rw\n",
+	} {
+		_, err = readMountInfo(strings.NewReader(line))
+		if !errors.Is(err, errMountInfoLine) {
+			t.Errorf("readMountInfo(%q) = %v, want %v", line, err,
+				errMountInfoLine)
+		}
+	}
+}
+
+func TestNonPersistentFilesystems(t *testing.T) {
+	t.Parallel()
+
+	if runtime.GOOS != goosLinux {
+		t.Skip("the test knows a mount only on Linux: /proc")
+	}
+
+	nonPersistent, err := nonPersistentFilesystems()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dev, ok := deviceOfPath("/proc")
+	if !ok {
+		t.Fatal("no device for /proc")
+	}
+
+	if got := nonPersistent[dev]; got != "proc" {
+		t.Errorf("filesystem of /proc = %q, want %q", got, "proc")
+	}
+}
+
+func TestDefaultExcludesHelp(t *testing.T) {
+	t.Parallel()
+
+	for _, goos := range []string{goosLinux, goosDarwin, goosWindows} {
+		help := defaultExcludesHelp(goos)
+
+		for _, dir := range defaultExcludes(goos) {
+			if !strings.Contains(help, "\n  "+dir+"\n") {
+				t.Errorf("help for %s does not list %s:\n%s", goos, dir, help)
+			}
+		}
+
+		// Only Linux and macOS list their mounted filesystems.
+		for _, fsType := range nonPersistentFilesystemTypes() {
+			listed := strings.Contains(help, " "+fsType+",") ||
+				strings.Contains(help, " "+fsType+"\n")
+			if listed != (goos != goosWindows) {
+				t.Errorf("help for %s lists %s: %v", goos, fsType, listed)
+			}
+		}
+	}
+
+	want := "This system has no default excludes.\n"
+	if got := defaultExcludesHelp("freebsd"); got != want {
+		t.Errorf("help for freebsd = %q, want %q", got, want)
+	}
+
+	// scan's help shows those of the system it runs on.
+	var stdout, stderr bytes.Buffer
+
+	run([]string{cmdScan, "-h"}, &stdout, &stderr)
+
+	help := strings.TrimSpace(defaultExcludesHelp(runtime.GOOS))
+	if !strings.Contains(stderr.String(), help) {
+		t.Errorf("scan --help = %q, want it to hold %q", stderr.String(), help)
+	}
+}
+
+// TestScanDoesNotEnterDefaultExclude checks that the walk does not
+// enter a default exclude below an operand. It says so on a line of its
+// own and does not count it as skipped. The records below it count as
+// outside the operands: the record of a file gone from it is kept,
+// while a file added to it is not recorded.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestScanDoesNotEnterDefaultExclude(t *testing.T) {
+	stderr := captureStderr(t)
+	dir := t.TempDir()
+	db := openTestDB(t)
+	excluded := filepath.Join(dir, "tmp")
+
+	// A scan with no default excludes records the file in excluded.
+	gone := writeFile(t, excluded, "gone", pattern(1, 100))
+	syncTree(t, db, dir)
+
+	err := os.Remove(gone)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	unseen := writeFile(t, excluded, "new", pattern(2, 10))
+
+	st, err := syncScan(t.Context(), db, []string{dir}, 1, false,
+		walkRules{excludes: []string{excluded}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if st.skipped != 0 {
+		t.Errorf("skipped = %d, want 0", st.skipped)
+	}
+
+	recs := dbRecords(t, db)
+	recordByPath(t, recs, gone)
+
+	if slices.Contains(recordPaths(recs), unseen) {
+		t.Errorf("%s recorded: the walk entered %s", unseen, excluded)
+	}
+
+	line := "\nscan: skipped " + excluded + " (default exclude)\n"
+	if !strings.Contains(stderr(), line) {
+		t.Errorf("stderr = %q, want %q", stderr(), line)
+	}
+}
+
+// TestScanWalksOperandInDefaultExclude checks that an operand at or
+// inside a default exclude is walked, also when it lies under another
+// operand, whose walk does not enter the default exclude.
+func TestScanWalksOperandInDefaultExclude(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	excluded := filepath.Join(dir, "tmp")
+	f := writeFile(t, excluded, "sub/f", pattern(1, 10))
+	sub := filepath.Dir(f)
+
+	cases := map[string][]string{
+		"at it":                      {excluded},
+		"inside it":                  {sub},
+		"inside it under an operand": {dir, sub},
+	}
+
+	for name, roots := range cases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			db := openTestDB(t)
+
+			st, err := syncScan(t.Context(), db, roots, 1, false,
+				walkRules{excludes: []string{excluded}})
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			if st.added != 1 {
+				t.Errorf("added = %d, want %s recorded once", st.added, f)
+			}
+
+			recordByPath(t, dbRecords(t, db), f)
+		})
+	}
+}
+
+// TestScanNamesNoDefaultExcludeThatIsAnOperand checks that a default
+// exclude given as an operand under another operand, which the walk of
+// that other operand does not enter, gets no line saying it was
+// skipped: it is walked as an operand of its own.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestScanNamesNoDefaultExcludeThatIsAnOperand(t *testing.T) {
+	stderr := captureStderr(t)
+	dir := t.TempDir()
+	db := openTestDB(t)
+	excluded := filepath.Join(dir, "tmp")
+	f := writeFile(t, excluded, "f", pattern(1, 10))
+
+	st, err := syncScan(t.Context(), db, []string{dir, excluded}, 1, false,
+		walkRules{excludes: []string{excluded}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if st.added != 1 {
+		t.Errorf("added = %d, want %s recorded once", st.added, f)
+	}
+
+	recordByPath(t, dbRecords(t, db), f)
+
+	if strings.Contains(stderr(), "scan: skipped") {
+		t.Errorf("stderr = %q, want no line for %s", stderr(), excluded)
+	}
+}
+
+// TestRunScanTempDirOperand scans a tree in the tests' temporary
+// directory, which on Linux lies inside the default exclude /tmp unless
+// TMPDIR names another place, with the system's own default excludes:
+// the scan walks the whole tree and reports no default exclude.
+func TestRunScanTempDirOperand(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := t.TempDir()
+	if !underAnyRoot(dir, defaultExcludes(runtime.GOOS)) {
+		t.Skip(dir + " is not inside a default exclude")
+	}
+
+	f := writeFile(t, dir, "sub/f", pattern(1, 10))
+
+	stderr := scanOK(t, dir)
+	if strings.Contains(stderr, "scan: skipped") {
+		t.Errorf("stderr = %q, want no line saying a path was skipped",
+			stderr)
+	}
+
+	assertRecorded(t, path, f, true)
+}
+
+// TestRunScanNoDefaultExcludes scans /var through the command. Its
+// /var/tmp, on a persistent filesystem, is a default exclude on Linux:
+// without --no-default-excludes the walk does not enter it and says so,
+// and with that flag the walk records a file the test puts there.
+func TestRunScanNoDefaultExcludes(t *testing.T) {
+	if runtime.GOOS != goosLinux {
+		t.Skip("only Linux has /var/tmp among its default excludes")
+	}
+
+	nonPersistent, err := nonPersistentFilesystems()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	rules := walkRules{nonPersistent: nonPersistent}
+
+	for _, dir := range []string{"/var", "/var/tmp"} {
+		fi, lstatErr := os.Lstat(dir)
+		if lstatErr != nil || !fi.IsDir() ||
+			rules.nonPersistentLine(dir, fi) != "" {
+			t.Skip(dir + " is not a directory on a persistent filesystem here")
+		}
+	}
+
+	//nolint:usetesting // the directory must be inside /var/tmp
+	tmp, err := os.MkdirTemp("/var/tmp", "sfdupes-test-")
+	if err != nil {
+		t.Skip("cannot write to /var/tmp here: " + err.Error())
+	}
+
+	t.Cleanup(func() { _ = os.RemoveAll(tmp) })
+
+	f := writeFile(t, tmp, "f", pattern(1, 10))
+
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	line := "scan: skipped /var/tmp (default exclude)\n"
+
+	if stderr := scanOK(t, "/var"); !strings.Contains(stderr, line) {
+		t.Errorf("scan /var: stderr = %q, want %q", stderr, line)
+	}
+
+	assertRecorded(t, path, f, false)
+
+	stderr := scanOK(t, "--no-default-excludes", "/var")
+	if strings.Contains(stderr, line) {
+		t.Errorf("scan --no-default-excludes /var: stderr = %q, want no %q",
+			stderr, line)
+	}
+
+	assertRecorded(t, path, f, true)
+}
+
+// TestRunScanSkipsNonPersistentOperand scans, through the command, a
+// directory on a filesystem that is not persistent, with and without
+// --no-default-excludes: either way it is skipped, with a line saying
+// so, and nothing in it is recorded.
+func TestRunScanSkipsNonPersistentOperand(t *testing.T) {
+	shm, fsType, _ := shmTempDir(t)
+	writeFile(t, shm, "f", pattern(1, 10))
+
+	t.Setenv(databaseEnv, testDBPath(t))
+
+	line := "scan: skipped " + shm + " (" + fsType +
+		", not a persistent filesystem)\n"
+	summary := "scan: 0 files seen"
+
+	for _, flags := range [][]string{nil, {"--no-default-excludes"}} {
+		stderr := scanOK(t, append(flags, shm)...)
+		if !strings.Contains(stderr, line) ||
+			!strings.Contains(stderr, summary) {
+			t.Errorf("scan %q: stderr = %q, want %q and %q", flags, stderr,
+				line, summary)
+		}
+	}
+}
+
+// TestScanKeepsRecordsOnNonPersistent scans a directory on a filesystem
+// that is not persistent beside one on the tests' temporary directory.
+// The records an earlier scan left in it count as outside the operands:
+// the record of a file gone from it is kept, while a file added to it
+// is not recorded.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestScanKeepsRecordsOnNonPersistent(t *testing.T) {
+	shm, fsType, rules := shmTempDir(t)
+	stderr := captureStderr(t)
+	dir := t.TempDir()
+	db := openTestDB(t)
+
+	// A scan that, without the list of filesystems, records gone.
+	gone := writeFile(t, shm, "gone", pattern(1, 100))
+	syncTree(t, db, shm)
+
+	err := os.Remove(gone)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	unseen := writeFile(t, shm, "new", pattern(2, 10))
+
+	st, err := syncScan(t.Context(), db, []string{shm, dir}, 1, false, rules)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if st.skipped != 0 {
+		t.Errorf("skipped = %d, want 0", st.skipped)
+	}
+
+	recs := dbRecords(t, db)
+	recordByPath(t, recs, gone)
+
+	if slices.Contains(recordPaths(recs), unseen) {
+		t.Errorf("%s recorded", unseen)
+	}
+
+	line := "scan: skipped " + shm + " (" + fsType +
+		", not a persistent filesystem)\n"
+	if !strings.Contains(stderr(), line) {
+		t.Errorf("stderr = %q, want %q", stderr(), line)
+	}
+}
+
+// TestWalkLeavesOutNonPersistent starts the walk itself in a directory
+// on a filesystem that is not persistent, which a scan never does: it
+// drops such an operand first. Below a directory on a persistent
+// filesystem, one on another takes a mount, which a test cannot make.
+// The walk enters no directory and records no file there, and names
+// each.
+func TestWalkLeavesOutNonPersistent(t *testing.T) {
+	t.Parallel()
+
+	shm, fsType, rules := shmTempDir(t)
+	f := writeFile(t, shm, "f", pattern(1, 10))
+	sub := filepath.Dir(writeFile(t, shm, "sub/g", pattern(1, 10)))
+
+	var leftOut []string
+
+	for ev := range startWalk(t.Context(), []string{shm}, false, rules, 1) {
+		if ev.rec.path != "" {
+			t.Errorf("walk recorded %s", ev.rec.path)
+		}
+
+		if ev.leftOut == "" {
+			continue
+		}
+
+		leftOut = append(leftOut, ev.leftOut)
+
+		want := "scan: skipped " + ev.leftOut + " (" + fsType +
+			", not a persistent filesystem)"
+		if ev.warn != want {
+			t.Errorf("line = %q, want %q", ev.warn, want)
+		}
+	}
+
+	slices.Sort(leftOut)
+
+	if want := []string{f, sub}; !slices.Equal(leftOut, want) {
+		t.Errorf("walk left out %q, want %q", leftOut, want)
+	}
+}
+
+// shmTempDir returns a new directory in /dev/shm, removed when the test
+// ends, the type of its filesystem, and the rules holding the real
+// filesystems that are not persistent. It skips the test where /dev/shm
+// is on a persistent filesystem, or cannot be written to.
+func shmTempDir(t *testing.T) (string, string, walkRules) {
+	t.Helper()
+
+	nonPersistent, err := nonPersistentFilesystems()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	dev, ok := deviceOfPath("/dev/shm")
+
+	fsType, found := nonPersistent[dev]
+	if !ok || !found {
+		t.Skip("/dev/shm is not a memory-backed filesystem here")
+	}
+
+	//nolint:usetesting // the directory must be inside /dev/shm
+	dir, err := os.MkdirTemp("/dev/shm", "sfdupes-test-")
+	if err != nil {
+		t.Skip("cannot write to /dev/shm here: " + err.Error())
+	}
+
+	t.Cleanup(func() { _ = os.RemoveAll(dir) })
+
+	return dir, fsType, walkRules{nonPersistent: nonPersistent}
+}
+
+// assertRecorded checks that the database at dbPath holds a record for
+// path when want is set, and none when it is not.
+func assertRecorded(t *testing.T, dbPath, path string, want bool) {
+	t.Helper()
+
+	db, err := openDB(dbPath, reportParams)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	if got := slices.Contains(recordPaths(dbRecords(t, db)), path); got != want {
+		t.Errorf("%s recorded: %v, want %v", path, got, want)
+	}
+}

go.mod

@@ -24,3 +24,5 @@ require (
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
 )
+
+retract v0.0.1 // early build without a database; does not work as the README describes

info.go

@@ -113,9 +113,6 @@ func writeInfo(stdout io.Writer, dbPath, source string,
 		dbFile.ModTime().UTC().Format(time.RFC3339))
 	fmt.Fprintf(&b, "schema version\t%d\n", counts.schemaVersion)
 	fmt.Fprintf(&b, "records\t%d\n", counts.records)
-	fmt.Fprintf(&b, "records with head and tail hashes\t%d\n",
-		counts.headTail)
-	fmt.Fprintf(&b, "records with content hash\t%d\n", counts.content)
 	fmt.Fprintf(&b, "size of recorded files\t%d (%s)\n",
 		counts.size, humanBytes(counts.size))
 

info_test.go

@@ -12,23 +12,25 @@ import (
 // infoOpenLine is the plain line of info's open phase when it opens the
 // database at once; it prints it as the phase starts and as it ends.
 const infoOpenLine = "[1/2] open: opening the database, elapsed 0s, " +
-	"eta unknown"
+	"remain unknown"
 
 // infoCountLine is the plain line of info's count phase when the count
 // takes under a second; it prints it as the phase starts and as it
 // ends.
 const infoCountLine = "[2/2] count: counting the records, elapsed 0s, " +
-	"eta unknown"
+	"remain unknown"
 
-// infoRecs are four records: a duplicate pair with every hash, a file
-// of 20 MiB with head and tail hashes but no content hash yet, and a
-// file never hashed.
+// infoRecs are four records: a duplicate pair, a file of 20 MiB and
+// another small file.
 func infoRecs() []scanRec {
+	h, tl, c, u := testHash("h"), testHash("t"), testHash("c"), testHash("u")
+	bigH, bigT, bigC := testHash("bh"), testHash("bt"), testHash("bc")
+
 	return []scanRec{
-		{size: 5, head: "h", tail: "t", content: "c", path: "/d/a"},
-		{size: 5, head: "h", tail: "t", content: "c", path: "/d/b"},
-		{size: 20 << 20, head: "bh", tail: "bt", path: "/d/big"},
-		{size: 7, path: "/d/unique"},
+		{size: 5, head: h, tail: tl, content: c, path: "/d/a"},
+		{size: 5, head: h, tail: tl, content: c, path: "/d/b"},
+		{size: 20 << 20, head: bigH, tail: bigT, content: bigC, path: "/d/big"},
+		{size: 7, head: u, tail: u, content: u, path: "/d/unique"},
 	}
 }
 
@@ -45,16 +47,12 @@ func TestRunInfo(t *testing.T) {
 		"empty": {
 			want: "schema version\t1\n" +
 				"records\t0\n" +
-				"records with head and tail hashes\t0\n" +
-				"records with content hash\t0\n" +
 				"size of recorded files\t0 (0 B)\n",
 		},
 		"filled": {
 			recs: infoRecs(),
 			want: "schema version\t1\n" +
 				"records\t4\n" +
-				"records with head and tail hashes\t3\n" +
-				"records with content hash\t2\n" +
 				"size of recorded files\t20971537 (20.0 MiB)\n",
 		},
 	}

main.go

@@ -1,18 +1,16 @@
 // Command sfdupes quickly identifies candidate duplicate files across
 // very large filesystems without reading every byte of every file.
 // Files are considered duplicates when their sizes are equal and they
-// agree on a short ladder of SHA-256 hashes. A file under 10 MiB is
-// hashed in full. A larger file is compared on the hashes of its first
-// and last 64 KiB, and only when those match another file's is its
-// content hash computed and compared: of the whole file when it is
-// under 50 MiB, or of gigabyte-spaced 1 MiB samples when it is 50 MiB
-// or larger. scan maintains a persistent SQLite database of file
-// signatures (SFDUPES_DATABASE, default /var/lib/sfdupes/db.sqlite)
-// that the other subcommands read.
+// agree on three SHA-256 hashes: of the first 64 KiB, of the last 64
+// KiB, and of the content. The content hash covers the whole file under
+// 100 MiB, and 1 MiB at each gigabyte at 100 MiB or more, so a large
+// file is never read in full. scan maintains a persistent SQLite
+// database of file signatures (SFDUPES_DATABASE, default
+// /var/lib/sfdupes/db.sqlite) that the other subcommands read.
 //
 // Usage:
 //
-//	sfdupes scan [--workers N] [-x] PATH...
+//	sfdupes scan [--workers N] [-x] [--no-default-excludes] PATH...
 //	sfdupes report > dupes.tsv
 //	sfdupes trees > dupetrees.tsv
 //	sfdupes info
@@ -28,6 +26,7 @@ import (
 	"io"
 	"os"
 	"runtime"
+	"runtime/debug"
 
 	"github.com/spf13/cobra"
 )
@@ -58,10 +57,32 @@ var errNoSubcommand = errors.New("no subcommand")
 var errWorkersBelowOne = errors.New("--workers must be at least 1")
 
 // Version is the build version, injected at link time via -ldflags
-// (see the Makefile); "dev" for a plain go build.
+// (see the Makefile); empty when the linker set none, as for a binary
+// built by go install. buildVersion turns it into what --version prints.
 //
 //nolint:gochecknoglobals // written only by the linker
-var Version = "dev"
+var Version string
+
+// buildVersion returns the version that sfdupes --version prints
+// (README "Install"): the version the linker set, when it set one;
+// otherwise the main module's version that Go recorded in the binary,
+// a tag such as v0.0.2 or the pseudo-version of an @main build; and
+// "dev" when neither is known. info is what debug.ReadBuildInfo
+// returns, nil when the binary carries none. Go records "(devel)" for
+// a build that has no version, such as one inside a copy of the source
+// without git.
+func buildVersion(linkerVersion string, info *debug.BuildInfo) string {
+	if linkerVersion != "" {
+		return linkerVersion
+	}
+
+	if info == nil || info.Main.Version == "" ||
+		info.Main.Version == "(devel)" {
+		return "dev"
+	}
+
+	return info.Main.Version
+}
 
 func main() {
 	// Once the reader of a stdout pipe has gone, as in "sfdupes report |
@@ -116,7 +137,10 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 	var showVersion bool
 
 	printVersion := runE(func(context.Context, []string) error {
-		_, err := fmt.Fprintf(stdout, "sfdupes %s\n", Version)
+		info, _ := debug.ReadBuildInfo()
+
+		_, err := fmt.Fprintf(stdout, "sfdupes %s\n",
+			buildVersion(Version, info))
 		if err != nil {
 			return fmt.Errorf("write stdout: %w", err)
 		}
@@ -182,17 +206,23 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 	return root
 }
 
-// newScanCommand builds the scan subcommand, with its --workers and -x
-// flags.
+// newScanCommand builds the scan subcommand, with its --workers, -x and
+// --no-default-excludes flags. Its help lists the default excludes of
+// the system it runs on, and the filesystem types it never records
+// anything on.
 func newScanCommand() *cobra.Command {
 	var (
-		scanWorkers int
-		scanOneFS   bool
+		scanWorkers           int
+		scanOneFS             bool
+		scanNoDefaultExcludes bool
 	)
 
+	short := "Walk trees and synchronize the scan database"
+
 	scanCmd := &cobra.Command{
-		Use:   cmdScan + " [--workers N] [-x] PATH...",
-		Short: "Walk trees and synchronize the scan database",
+		Use:   cmdScan + " [--workers N] [-x] [--no-default-excludes] PATH...",
+		Short: short,
+		Long:  short + ".\n\n" + defaultExcludesHelp(runtime.GOOS),
 		Args:  cobra.MinimumNArgs(1),
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			return checkScanWorkers(cmd, scanWorkers)
@@ -201,13 +231,16 @@ func newScanCommand() *cobra.Command {
 			ctx, stop := interruptContext(ctx)
 			defer stop()
 
-			return runScan(ctx, args, scanWorkers, scanOneFS)
+			return runScan(ctx, args, scanWorkers, scanOneFS,
+				scanNoDefaultExcludes)
 		}),
 	}
 	scanCmd.Flags().IntVar(&scanWorkers, "workers", runtime.NumCPU(),
-		"concurrent workers for the walk, hash, and content phases")
+		"concurrent workers for the walk and hash phases")
 	scanCmd.Flags().BoolVarP(&scanOneFS, "one-file-system", "x", false,
 		"do not cross filesystem boundaries")
+	scanCmd.Flags().BoolVar(&scanNoDefaultExcludes, "no-default-excludes",
+		false, "enter the default excludes, the paths listed above")
 
 	return scanCmd
 }

main_test.go

@@ -4,10 +4,12 @@ import (
 	"bytes"
 	"context"
 	"errors"
+	"fmt"
 	"io"
 	"io/fs"
 	"os"
 	"path/filepath"
+	"runtime/debug"
 	"slices"
 	"strconv"
 	"strings"
@@ -18,6 +20,36 @@ import (
 // error prints and a runtime failure must not.
 const usageMarker = "Usage:"
 
+// TestMain stops the tests at once, saying why, when their temporary
+// directory is not on a persistent filesystem: scan records nothing
+// there (README "Rules for the walk"), so most scan tests would fail
+// without saying why.
+func TestMain(m *testing.M) {
+	nonPersistent, err := nonPersistentFilesystems()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "list the mounted filesystems: %v\n", err)
+		os.Exit(1)
+	}
+
+	dir := os.TempDir()
+
+	fi, err := os.Stat(dir)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	dev, ok := deviceOfInfo(fi)
+	if fsType, found := nonPersistent[dev]; ok && found {
+		fmt.Fprintf(os.Stderr, "%s is on %s, not a persistent filesystem, "+
+			"and scan records nothing there: set TMPDIR to a directory on a "+
+			"persistent filesystem\n", dir, fsType)
+		os.Exit(1)
+	}
+
+	os.Exit(m.Run())
+}
+
 // walSuffixes are the SQLite sidecar files a WAL-mode database keeps
 // while it is open. A clean close checkpoints the WAL and removes
 // both; finding either afterwards means the database was never closed.
@@ -535,7 +567,7 @@ func TestRunNamesDefaultDatabase(t *testing.T) {
 	}{
 		cmdScan: {
 			run: func() error {
-				return runScan(t.Context(), []string{missing}, 1, false)
+				return runScan(t.Context(), []string{missing}, 1, false, false)
 			},
 			want: scanWant,
 		},
@@ -683,6 +715,8 @@ func TestRunVersion(t *testing.T) {
 
 	// README §Subcommands: the version is one line on stdout, with
 	// nothing on stderr, and exits 0.
+	info, _ := debug.ReadBuildInfo()
+
 	for _, arg := range []string{"--version", "-v"} {
 		var stdout, stderr bytes.Buffer
 
@@ -691,7 +725,7 @@ func TestRunVersion(t *testing.T) {
 			t.Errorf("run(%s) = %d, want %d", arg, code, exitOK)
 		}
 
-		want := "sfdupes " + Version + "\n"
+		want := "sfdupes " + buildVersion(Version, info) + "\n"
 		if got := stdout.String(); got != want {
 			t.Errorf("run(%s) stdout = %q, want %q", arg, got, want)
 		}
@@ -702,6 +736,40 @@ func TestRunVersion(t *testing.T) {
 	}
 }
 
+func TestBuildVersion(t *testing.T) {
+	t.Parallel()
+
+	// README "Install": the linker's version wins; otherwise the main
+	// module's version that Go recorded; "dev" when neither is known.
+	tagged := &debug.BuildInfo{Main: debug.Module{Version: "v0.0.2"}}
+	pseudo := &debug.BuildInfo{Main: debug.Module{
+		Version: "v1.0.0-rc2.0.20261016120000-4e4a94d0c2a1",
+	}}
+	devel := &debug.BuildInfo{Main: debug.Module{Version: "(devel)"}}
+
+	cases := []struct {
+		name   string
+		linker string
+		info   *debug.BuildInfo
+		want   string
+	}{
+		{"linker set", "v0.0.2-3-g4e4a94d", tagged, "v0.0.2-3-g4e4a94d"},
+		{"linker set, no build info", "4e4a94d", nil, "4e4a94d"},
+		{"build info with a tag", "", tagged, "v0.0.2"},
+		{"build info with a pseudo-version", "", pseudo,
+			"v1.0.0-rc2.0.20261016120000-4e4a94d0c2a1"},
+		{"(devel)", "", devel, "dev"},
+		{"no build info", "", nil, "dev"},
+	}
+
+	for _, c := range cases {
+		if got := buildVersion(c.linker, c.info); got != c.want {
+			t.Errorf("%s: buildVersion(%q, ...) = %q, want %q",
+				c.name, c.linker, got, c.want)
+		}
+	}
+}
+
 func TestRunVersionWriteFailureIsFatal(t *testing.T) {
 	t.Parallel()
 
@@ -860,24 +928,21 @@ func TestRunScanWalksOperandUnderSymlinkOperand(t *testing.T) {
 }
 
 func TestRunScanSkipsZFSOperand(t *testing.T) {
-	path := testDBPath(t)
-	t.Setenv(databaseEnv, path)
-
 	zfs := filepath.Join(t.TempDir(), ".zfs")
-	snapshot := filepath.Join(zfs, "snapshot", "hourly")
-	f := writeFile(t, snapshot, "f", pattern(1, 10))
+	f := writeFile(t, zfs, "snapshot/hourly/f", pattern(1, 10))
 
-	// An operand beneath a .zfs directory is walked, because it is not
-	// itself named .zfs.
-	scanOK(t, snapshot)
+	// No scan records a file inside a .zfs directory, so the record
+	// beneath the operand is written straight into the database.
+	path := seedDatabase(t, []scanRec{{size: 10, path: f}})
+	t.Setenv(databaseEnv, path)
 
 	assertOperandSkipped(t, path, zfs, ".zfs directory", f)
 }
 
 // assertOperandSkipped scans operand alone and checks that it is skipped
 // as kind: a warning naming it, one skip in the summary, exit 0, and the
-// record for kept, which an earlier scan stored beneath operand, still
-// in the database at dbPath.
+// record for kept, stored beneath operand before this scan, still in the
+// database at dbPath.
 func assertOperandSkipped(t *testing.T, dbPath, operand, kind,
 	kept string,
 ) {
@@ -906,6 +971,121 @@ func assertOperandSkipped(t *testing.T, dbPath, operand, kind,
 	recordByPath(t, dbRecords(t, db), kept)
 }
 
+// TestRunScanSkipsOperandInsideZFS scans a directory inside a .zfs
+// directory, first alone and then under another operand. Each time it
+// is warned about and counted as skipped, and nothing in it is walked.
+// The other operand is scanned as usual.
+func TestRunScanSkipsOperandInsideZFS(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := t.TempDir()
+	hourly := filepath.Join(dir, ".zfs", "snapshot", "hourly")
+	writeFile(t, hourly, "f", pattern(1, 10))
+	f := writeFile(t, dir, "f", pattern(2, 10))
+
+	warning := "walk " + hourly + ": skipping operand inside a .zfs directory\n"
+
+	for _, tc := range []struct {
+		operands []string
+		summary  string
+	}{
+		{
+			[]string{hourly},
+			"scan: 0 files seen (0 added, 0 updated, 0 removed, " +
+				"0 unchanged), 1 skipped\n",
+		},
+		{
+			[]string{dir, hourly},
+			"scan: 1 files seen (1 added, 0 updated, 0 removed, " +
+				"0 unchanged), 1 skipped\n",
+		},
+	} {
+		stderr := scanOK(t, tc.operands...)
+		if !strings.Contains(stderr, warning) ||
+			!strings.Contains(stderr, tc.summary) {
+			t.Errorf("scan %q: stderr = %q, want %q and %q", tc.operands,
+				stderr, warning, tc.summary)
+		}
+	}
+
+	db, err := openDB(path, reportParams)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	if got := recordPaths(dbRecords(t, db)); !slices.Equal(got, []string{f}) {
+		t.Errorf("records = %q, want %q", got, []string{f})
+	}
+}
+
+// TestRunScanSkipsOperandThroughSymlinkIntoZFS scans snaps/daily, where
+// snaps is a symlink to pool/.zfs/snapshot. The operand is warned about
+// by the path given, counted as skipped, and not walked.
+func TestRunScanSkipsOperandThroughSymlinkIntoZFS(t *testing.T) {
+	t.Setenv(databaseEnv, testDBPath(t))
+
+	dir := t.TempDir()
+	writeFile(t, dir, "pool/.zfs/snapshot/daily/f", pattern(1, 10))
+
+	snaps := filepath.Join(dir, "snaps")
+
+	err := os.Symlink(filepath.Join(dir, "pool", ".zfs", "snapshot"), snaps)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	daily := filepath.Join(snaps, "daily")
+	stderr := scanOK(t, daily)
+
+	warning := "walk " + daily + ": skipping operand inside a .zfs directory\n"
+	summary := "scan: 0 files seen (0 added, 0 updated, 0 removed, " +
+		"0 unchanged), 1 skipped\n"
+
+	if !strings.Contains(stderr, warning) ||
+		!strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q and %q", stderr, warning, summary)
+	}
+}
+
+// TestRunScanWalksOperandThroughSymlink scans data/daily, where data is
+// a symlink to a directory outside any .zfs directory. The operand is
+// scanned as usual, and its file is recorded by the path given.
+func TestRunScanWalksOperandThroughSymlink(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := t.TempDir()
+	writeFile(t, dir, "pool/data/daily/f", pattern(1, 10))
+
+	data := filepath.Join(dir, "data")
+
+	err := os.Symlink(filepath.Join(dir, "pool", "data"), data)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	daily := filepath.Join(data, "daily")
+	stderr := scanOK(t, daily)
+
+	summary := "scan: 1 files seen (1 added, 0 updated, 0 removed, " +
+		"0 unchanged), 0 skipped\n"
+	if !strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q", stderr, summary)
+	}
+
+	db, err := openDB(path, reportParams)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	recordByPath(t, dbRecords(t, db), filepath.Join(daily, "f"))
+}
+
 func TestRunReportSucceeds(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)

progress.go

@@ -9,6 +9,7 @@ import (
 	"strings"
 	"sync"
 	"time"
+	"unicode/utf8"
 
 	"github.com/schollz/progressbar/v3"
 	"golang.org/x/term"
@@ -22,13 +23,29 @@ const plainInterval = 5 * time.Second
 // a TTY.
 const redrawInterval = 100 * time.Millisecond
 
+// rateWindow is the time the rate a display shows covers: the items
+// completed over the last rateWindow, which is the time since the line
+// before when stderr is not a TTY.
+const rateWindow = 5 * time.Second
+
+// stallTime is how long a phase goes with no item completed before its
+// line says it has stalled, and where it waits, in place of the rate.
+const stallTime = 10 * time.Second
+
 // spinnerType selects the progressbar library's spinner style.
 const spinnerType = 14
 
-// barWidth is the width of the progressbar library's bar between its
-// two ends, as in the example line in README "Progress".
+// barWidth is the width of a phase's bar between its two ends, as in
+// the example line in README "Progress".
 const barWidth = 10
 
+// barCell is one column of the filled part of a bar.
+const barCell = "█"
+
+// barColumns is the width of what percentBar returns: the percent in
+// four columns and its sign, a space, and the bar with its two ends.
+const barColumns = barWidth + 8
+
 // percentScale converts a fraction to a percentage.
 const percentScale = 100
 
@@ -36,17 +53,12 @@ const percentScale = 100
 // read, as the progressbar library takes it.
 const fallbackWidth = 80
 
-// spinnerMargin is the columns of a spinner's line besides its text:
-// the spinner and the three spaces the library draws around the text,
-// and the terminal's last column, which every line stays clear of so
-// that no terminal wraps it.
+// spinnerMargin is the columns of a line besides its text: the spinner
+// and the three spaces the library draws around the text, and the
+// terminal's last column, which every line stays clear of so that no
+// terminal wraps it.
 const spinnerMargin = 5
 
-// barMargin is the columns of a bar's line besides its text: the
-// percent and the bar the library draws after the text, the spaces
-// around them, and the terminal's last column.
-const barMargin = barWidth + 11
-
 // countingRecords is what the display of a phase that reads the records
 // says while it counts them, before it has its total.
 const countingRecords = "counting the records"
@@ -76,7 +88,7 @@ func terminalWidth() int {
 	return width
 }
 
-// phaseLabel names phase with its place among phases, as "[2/5] walk".
+// phaseLabel names phase with its place among phases, as "[2/4] walk".
 func phaseLabel(phases []string, phase string) string {
 	return fmt.Sprintf("[%d/%d] %s",
 		slices.Index(phases, phase)+1, len(phases), phase)
@@ -89,16 +101,24 @@ type progressParams struct {
 	total      int64  // the items the phase will complete; -1 when not known
 	estimate   bool   // total is an estimate, which the count may pass
 	waitingFor string // what the phase waits for until setTotal is called
+	stalledOn  string // where the phase waits, as "disk/db"; see stallTime
+}
+
+// drawnCount is the count of items completed as of one draw, and when
+// that draw was.
+type drawnCount struct {
+	at    time.Time
+	count int64
 }
 
 // progress renders one phase's progress on stderr. On a TTY the
-// progressbar library draws line, fitted to the terminal's width: after
-// the library's spinner, or, for a phase with an exact total, before the
-// library's bar when the terminal has room for the bar beside it. It is
-// drawn again every redrawInterval, so its elapsed time keeps moving
-// while the phase waits for its next item. When stderr is not a TTY it
-// emits no ANSI redraws: it prints line as the phase starts, every
-// plainInterval while it runs, and as it ends.
+// progressbar library draws its spinner and then line, fitted to the
+// terminal's width. A phase with an exact total ends the line with its
+// percent and bar, at the terminal's right edge, when the terminal has
+// room for them. It is drawn again every redrawInterval, so its elapsed
+// time keeps moving while the phase waits for its next item. When
+// stderr is not a TTY it emits no ANSI redraws: it prints line as the
+// phase starts, every plainInterval while it runs, and as it ends.
 //
 // The draws come from a goroutine of their own, so mu guards the fields
 // below it. Every method must be called from the main goroutine. A nil
@@ -107,46 +127,55 @@ type progressParams struct {
 // phase's helpers without rendering anything, and its writer writes
 // with no display to clear.
 type progress struct {
-	width func() int    // reads the terminal's width; nil when not a TTY
-	stop  chan struct{} // closed by finish to end the draws
-	done  chan struct{} // closed once the draws have ended
+	now   func() time.Time // reads the time
+	width func() int       // reads the terminal's width; nil when not a TTY
+	stop  chan struct{}    // closed by finish to end the draws
+	done  chan struct{}    // closed once the draws have ended
 
 	mu         sync.Mutex
 	bar        *progressbar.ProgressBar // what the library draws; nil until then
-	withBar    bool                     // bar is the library's bar, not its spinner
 	widest     int                      // the widest line bar has drawn, in columns
 	label      string
 	unit       string
 	total      int64
 	estimate   bool
 	waitingFor string
+	stalledOn  string
 	count      int64
 	start      time.Time // when the phase started, for the elapsed time
-	rateStart  time.Time // when the count started, for the rate
+	rateStart  time.Time // when the count started, for the time remaining
+	lastItem   time.Time // when the last item was completed, or the count started
+	// drawn holds the count at each draw over the last rateWindow, oldest
+	// first; the rate counts from the first. It keeps the draw before the
+	// latest even when that is older, as the line before is when lines
+	// are plainInterval apart and a tick comes late.
+	drawn []drawnCount
 }
 
 // newProgress starts the display of one phase on stderr.
 func newProgress(params progressParams) *progress {
 	if stderrIsTTY() {
-		return startProgress(params, terminalWidth, redrawInterval)
+		return startProgress(params, terminalWidth, redrawInterval, time.Now)
 	}
 
-	return startProgress(params, nil, plainInterval)
+	return startProgress(params, nil, plainInterval, time.Now)
 }
 
 // startProgress shows the phase params describes at once, and again
 // every interval until finish: with the progressbar library on a
 // terminal, whose width each draw reads by calling width, or as a plain
-// line when width is nil.
+// line when width is nil. The display reads the time by calling now.
 func startProgress(params progressParams, width func() int,
-	interval time.Duration,
+	interval time.Duration, now func() time.Time,
 ) *progress {
-	now := time.Now()
+	start := now()
 	p := &progress{
-		width: width, stop: make(chan struct{}), done: make(chan struct{}),
+		now: now, width: width,
+		stop: make(chan struct{}), done: make(chan struct{}),
 		label: params.label, unit: params.unit, total: params.total,
 		estimate: params.estimate, waitingFor: params.waitingFor,
-		start: now, rateStart: now,
+		stalledOn: params.stalledOn, start: start, rateStart: start,
+		lastItem: start, drawn: []drawnCount{{at: start}},
 	}
 
 	// Show the zero state at once: the first item may take minutes,
@@ -173,60 +202,49 @@ func startProgress(params progressParams, width func() int,
 }
 
 // draw shows the phase's progress: on a TTY in place of the line
-// before, and otherwise as a plain line.
+// before, and otherwise as a plain line. It first adds the count to
+// drawn, then drops from drawn the draws older than rateWindow, except
+// the one before this draw.
 func (p *progress) draw() {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
+	now := p.now()
+
+	p.drawn = append(p.drawn, drawnCount{at: now, count: p.count})
+	for len(p.drawn) > 2 && now.Sub(p.drawn[0].at) > rateWindow {
+		p.drawn = p.drawn[1:]
+	}
+
 	if p.width == nil {
-		text, _ := p.line(math.MaxInt, true)
-		fmt.Fprintln(os.Stderr, text)
+		fmt.Fprintln(os.Stderr, p.line(now, math.MaxInt, false))
 
 		return
 	}
 
 	width := p.width()
+	text := p.line(now, width-spinnerMargin, true)
 
-	// A phase with an exact total gets the library's bar when its line,
-	// without the percent the bar shows, fits whole beside the bar. A
-	// total of 0 leaves the bar nothing to fill.
-	text, withBar := "", false
-	if p.total > 0 && !p.estimate {
-		text, withBar = p.line(width-barMargin, false)
-	}
-
-	margin := barMargin
-	if !withBar {
-		margin = spinnerMargin
-		text, _ = p.line(width-margin, true)
-	}
-
-	// The library makes a bar or a spinner, and before each draw erases
-	// its line with as many spaces as the widest line it has drawn. A
-	// display gets a new one when it turns from one to the other, as its
-	// line grows or the terminal is resized, and when the terminal has
-	// been made too narrow for that erase, which would wrap and leave a
-	// line behind at every draw.
-	if p.bar == nil || p.withBar != withBar || p.widest >= width {
-		p.newBar(withBar, width)
-	}
-
-	if withBar {
-		_ = p.bar.Set64(p.count)
+	// Before each draw the library erases its line with as many spaces as
+	// the widest line it has drawn. A display gets a new one when the
+	// terminal has been made too narrow for that erase, which would wrap
+	// and leave a line behind at every draw.
+	if p.bar == nil || p.widest >= width {
+		p.newBar(width)
 	}
 
 	p.bar.Describe(text)
 
-	// The library drew the text and its margin, less the terminal's last
-	// column, which the margin keeps clear.
-	p.widest = max(p.widest, len(text)+margin-1)
+	// The library drew the spinner, the text and the spaces around it,
+	// less the terminal's last column, which spinnerMargin keeps clear. A
+	// bar's cells take one column each but more than one byte.
+	p.widest = max(p.widest, utf8.RuneCountInString(text)+spinnerMargin-1)
 }
 
-// newBar has the library make what draw draws: a bar for the phase's
-// total when withBar is set, and a spinner when not. Either shows the
-// text draw gives it, and nothing of its own besides the spinner, or
-// the bar and its percent. p.mu must be held.
-func (p *progress) newBar(withBar bool, width int) {
+// newBar has the library make what draw draws: its spinner, followed by
+// the text draw gives it and nothing of the library's own. p.mu must be
+// held.
+func (p *progress) newBar(width int) {
 	if p.bar != nil {
 		// Erase what was drawn before, short of the last column of a
 		// terminal that may have been made narrower since: the library's
@@ -235,38 +253,49 @@ func (p *progress) newBar(withBar bool, width int) {
 		fmt.Fprint(os.Stderr, "\r"+blank+"\r")
 	}
 
-	total := int64(-1) // the library's spinner
-	if withBar {
-		total = p.total
-	}
-
-	p.bar = progressbar.NewOptions64(total,
+	// A total of -1 gives the library's spinner.
+	p.bar = progressbar.NewOptions64(-1,
 		progressbar.OptionSetWriter(os.Stderr),
-		progressbar.OptionSetWidth(barWidth),
 		progressbar.OptionSpinnerType(spinnerType),
 		// The spinner turns at each draw, not on a timer of the
 		// library's own.
 		progressbar.OptionSetSpinnerChangeInterval(0),
-		// The text carries the elapsed time and the ETA.
+		// The text carries the elapsed time and the time remaining.
 		progressbar.OptionSetElapsedTime(false),
 		progressbar.OptionSetPredictTime(false),
 	)
-	p.withBar, p.widest = withBar, 0
+	p.widest = 0
+}
+
+// percentBar returns the percent and the bar that end the text of a
+// phase with an exact total, as "  25% |██        |": the bar's
+// barWidth columns fill in proportion to the items done. A count past
+// the total, as when a scan adds records while trees reads them, shows
+// as 100%. p.mu must be held.
+func (p *progress) percentBar() string {
+	done := min(float64(p.count)/float64(p.total), 1)
+	filled := strings.Repeat(barCell, int(done*barWidth))
+
+	return fmt.Sprintf("%4.0f%% |%-*s|", done*percentScale, barWidth, filled)
 }
 
 // setTotal gives a phase that started without a total its total, once
-// it is known. The rate, and so the ETA, count from then on: the time
-// spent waiting for the total says nothing about how fast items go.
+// it is known. The rate, the time remaining and the time with no item
+// completed count from then on: the time spent waiting for the total
+// says nothing about how fast items go.
 func (p *progress) setTotal(total int64) {
 	if p == nil {
 		return
 	}
 
+	now := p.now()
+
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
 	p.total = total
-	p.rateStart = time.Now()
+	p.rateStart, p.lastItem = now, now
+	p.drawn = []drawnCount{{at: now, count: p.count}}
 }
 
 // increment records one completed item, which the display shows at its
@@ -276,10 +305,13 @@ func (p *progress) increment() {
 		return
 	}
 
+	now := p.now()
+
 	p.mu.Lock()
 	defer p.mu.Unlock()
 
 	p.count++
+	p.lastItem = now
 }
 
 // warnf prints a one-line warning to stderr without corrupting the
@@ -391,50 +423,92 @@ func (p *progress) finish() {
 	}
 }
 
-// line formats the phase's progress in at most room columns, as
+// line formats the phase's progress as of now in at most room columns,
+// as
 //
-//	[3/5] hash: [1234/5000] 25%, 300 files/s, elapsed 4s, eta 13s
+//	[3/4] hash: [1234/5000] 25%, 300 files/s, elapsed 4s, remain 13s
 //
-// where "files" is the phase's unit, without the percent when percent
-// is false, as before the library's bar, which shows its own. A phase
-// with no total shows the items done instead, or what it waits for.
+// where "files" is the phase's unit. A phase with no total shows the
+// items done instead, or what it waits for. The rate is that since the
+// first draw in drawn, and the time remaining comes from the rate since
+// the count started. Once no item has been completed for stallTime, the
+// rate, which would read 0, gives way to the word "stalled" and where
+// the phase waits, as "stalled disk/db".
 //
-// The phase and its place, the progress, the elapsed time and the ETA
-// are kept whole. A line wider than room leaves out the rate, or what
-// the phase waits for; only if it is still wider is it cut at room, and
-// line reports that it does not fit. Every part is ASCII, so its length
-// is its width in columns. p.mu must be held.
-func (p *progress) line(room int, percent bool) (string, bool) {
-	elapsed := time.Since(p.start).Round(time.Second)
+// When bar is true, as on a terminal, a phase with an exact total ends
+// the line with its percent and bar, in place of the percent after its
+// count. A total of 0 leaves the bar nothing to fill.
+//
+// The phase and its place, the progress, the elapsed time and the time
+// remaining are kept whole. A line wider than room first leaves out the
+// rate, the words of a stalled phase, or what the phase waits for. Next
+// it leaves out the bar. Only if it is still wider is it cut at room.
+// Every part but the bar is ASCII, so its length is its width in
+// columns. p.mu must be held.
+func (p *progress) line(now time.Time, room int, bar bool) string {
+	elapsed := now.Sub(p.start).Round(time.Second)
 
 	// head and tail hold the parts kept whole; extra, between them, is
 	// the part left out.
 	var head, extra, tail string
 
 	if p.total < 0 && p.waitingFor != "" {
-		head, extra = p.label+": ", p.waitingFor
-		tail = fmt.Sprintf("elapsed %s, eta unknown", elapsed)
+		head, extra = p.label+": ", p.waitingFor+", "
+		tail = fmt.Sprintf("elapsed %s, remain unknown", elapsed)
 	} else {
-		rate := 0.0
-		if s := time.Since(p.rateStart).Seconds(); s > 0 {
-			rate = float64(p.count) / s
-		}
+		since := p.drawn[0]
+		rate := perSecond(p.count-since.count, now.Sub(since.at))
+		average := perSecond(p.count, now.Sub(p.rateStart))
 
-		head = p.label + ": " + p.itemsDone(percent) + ", "
-		extra = fmt.Sprintf("%.0f %s/s", rate, p.unit)
-		tail = fmt.Sprintf("elapsed %s, eta %s", elapsed, p.eta(rate))
+		head = p.label + ": " + p.itemsDone(true) + ", "
+		extra = fmt.Sprintf("%.0f %s/s, ", rate, p.unit)
+		tail = fmt.Sprintf("elapsed %s, remain %s", elapsed, p.remain(average))
+
+		if now.Sub(p.lastItem) >= stallTime {
+			extra = "stalled " + p.stalledOn + ", "
+		}
 	}
 
-	full, kept := head+extra+", "+tail, head+tail
+	if bar && p.total > 0 && !p.estimate {
+		// Beside the bar, which shows the percent, the count shows none.
+		// The line is padded to the room the bar leaves it, so the bar
+		// stays at room's right edge however long the line is.
+		beside := room - barColumns
+		barHead := p.label + ": " + p.itemsDone(false) + ", "
+
+		switch {
+		case len(barHead+extra+tail) <= beside:
+			return fmt.Sprintf("%-*s%s", beside, barHead+extra+tail,
+				p.percentBar())
+		case len(barHead+tail) <= beside:
+			return fmt.Sprintf("%-*s%s", beside, barHead+tail, p.percentBar())
+		}
+
+		// The bar gives way. The rate, or the words of a stalled phase,
+		// gave way before it and stay out.
+		extra = ""
+	}
+
+	full, kept := head+extra+tail, head+tail
 
 	switch {
 	case len(full) <= room:
-		return full, true
+		return full
 	case len(kept) <= room:
-		return kept, true
+		return kept
 	}
 
-	return kept[:max(room, 0)], false
+	return kept[:max(room, 0)]
+}
+
+// perSecond returns count items over d as items a second, or 0 when no
+// time has passed.
+func perSecond(count int64, d time.Duration) float64 {
+	if d <= 0 {
+		return 0
+	}
+
+	return float64(count) / d.Seconds()
 }
 
 // itemsDone formats the items done, as "[1234/5000] 25%", with "~"
@@ -464,10 +538,10 @@ func (p *progress) itemsDone(percent bool) string {
 	return fmt.Sprintf("%s %.0f%%", done, pct)
 }
 
-// eta returns the time the phase has left at rate items a second, or
+// remain returns the time the phase has left at rate items a second, or
 // "unknown": with no total, before the first item, and once the count
 // passes an estimate. p.mu must be held.
-func (p *progress) eta(rate float64) string {
+func (p *progress) remain(rate float64) string {
 	switch {
 	case p.total < 0, p.estimate && p.count > p.total:
 		return "unknown"
@@ -477,8 +551,8 @@ func (p *progress) eta(rate float64) string {
 		return "unknown"
 	}
 
-	remaining := time.Duration(
+	left := time.Duration(
 		float64(p.total-p.count) / rate * float64(time.Second))
 
-	return remaining.Round(time.Second).String()
+	return left.Round(time.Second).String()
 }

progress_test.go

@@ -6,7 +6,9 @@ import (
 	"math"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 	"unicode/utf8"
@@ -20,6 +22,33 @@ const testRedraw = time.Millisecond
 // it expects.
 const testDeadline = 5 * time.Second
 
+// hashStalledOn is where the hash phase says it waits once it has
+// stalled, as hashPhase gives it.
+const hashStalledOn = "disk/db"
+
+// testClock is a clock a test moves by hand, for a display that reads
+// it from its own goroutine too.
+type testClock struct {
+	mu  sync.Mutex
+	now time.Time
+}
+
+// Now returns the clock's time.
+func (c *testClock) Now() time.Time {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	return c.now
+}
+
+// Add moves the clock on by d.
+func (c *testClock) Add(d time.Duration) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.now = c.now.Add(d)
+}
+
 //nolint:paralleltest // replaces the process-wide os.Stderr
 func TestStderrIsTTYFalseForNonTerminals(t *testing.T) {
 	r, pipe, err := os.Pipe()
@@ -72,11 +101,13 @@ func TestPhaseLabel(t *testing.T) {
 }
 
 // TestProgressLine checks the line a display shows in each state, ten
-// seconds into the phase.
+// seconds into the phase, with no draw since the first and the last
+// item just completed.
 func TestProgressLine(t *testing.T) {
 	t.Parallel()
 
-	ago := time.Now().Add(-10 * time.Second)
+	now := time.Now()
+	ago := now.Add(-10 * time.Second)
 
 	cases := []struct {
 		p    *progress
@@ -86,38 +117,38 @@ func TestProgressLine(t *testing.T) {
 			label: scanPhase("load"), total: -1,
 			waitingFor: countingRecords,
 		},
-		want: "[1/5] load: counting the records, elapsed 10s, eta unknown",
+		want: "[1/4] load: counting the records, elapsed 10s, remain unknown",
 	}, {
 		p: &progress{
 			label: scanPhase("hash"), unit: scanUnit, total: 100, count: 20,
 		},
-		want: "[3/5] hash: [20/100] 20%, 2 files/s, elapsed 10s, eta 40s",
+		want: "[3/4] hash: [20/100] 20%, 2 files/s, elapsed 10s, remain 40s",
 	}, {
 		p:    &progress{label: scanPhase("hash"), unit: scanUnit, total: 100},
-		want: "[3/5] hash: [0/100] 0%, 0 files/s, elapsed 10s, eta unknown",
+		want: "[3/4] hash: [0/100] 0%, 0 files/s, elapsed 10s, remain unknown",
 	}, {
 		p:    &progress{label: scanPhase("update"), unit: scanUnit, total: 0},
-		want: "[4/5] update: [0/0] 100%, 0 files/s, elapsed 10s, eta 0s",
+		want: "[4/4] update: [0/0] 100%, 0 files/s, elapsed 10s, remain 0s",
 	}, {
 		p: &progress{
 			label: scanPhase("walk"), unit: scanUnit, total: 100,
 			estimate: true, count: 20,
 		},
-		want: "[2/5] walk: [20/~100] 20%, 2 files/s, elapsed 10s, eta 40s",
+		want: "[2/4] walk: [20/~100] 20%, 2 files/s, elapsed 10s, remain 40s",
 	}, {
 		// Past the estimate the walk cannot tell how long it has left.
 		p: &progress{
 			label: scanPhase("walk"), unit: scanUnit, total: 100,
 			estimate: true, count: 120,
 		},
-		want: "[2/5] walk: [120/~100] 120%, 12 files/s, elapsed 10s, " +
-			"eta unknown",
+		want: "[2/4] walk: [120/~100] 120%, 12 files/s, elapsed 10s, " +
+			"remain unknown",
 	}, {
 		// A first scan's walk has no estimate.
 		p: &progress{
 			label: scanPhase("walk"), unit: scanUnit, total: -1, count: 20,
 		},
-		want: "[2/5] walk: 20 files, 2 files/s, elapsed 10s, eta unknown",
+		want: "[2/4] walk: 20 files, 2 files/s, elapsed 10s, remain unknown",
 	}, {
 		// The rate is in what the phase counts.
 		p: &progress{
@@ -125,94 +156,125 @@ func TestProgressLine(t *testing.T) {
 			count: 20,
 		},
 		want: "[3/4] group: [20/100] 20%, 2 directories/s, elapsed 10s, " +
-			"eta 40s",
+			"remain 40s",
 	}}
 
 	for _, tc := range cases {
-		tc.p.start, tc.p.rateStart = ago, ago
+		tc.p.start, tc.p.rateStart, tc.p.lastItem = ago, ago, now
+		tc.p.drawn = []drawnCount{{at: ago}}
 
-		if got, _ := tc.p.line(math.MaxInt, true); got != tc.want {
+		if got := tc.p.line(now, math.MaxInt, false); got != tc.want {
 			t.Errorf("line = %q, want %q", got, tc.want)
 		}
 	}
 }
 
 // TestLineFitsRoom checks how a line is fitted to the room it has, ten
-// seconds into the phase: it leaves out the rate, or what the phase
-// waits for, and is cut only when what is left is still too wide.
+// seconds into the phase, and fifty into a phase with no file read for
+// the last 42: it leaves out the rate, what the phase waits for, or the
+// words of a stalled phase, and is cut only when what is left is still
+// too wide.
 func TestLineFitsRoom(t *testing.T) {
 	t.Parallel()
 
-	ago := time.Now().Add(-10 * time.Second)
+	now := time.Now()
+	ago := now.Add(-10 * time.Second)
 	hash := &progress{
 		label: scanPhase("hash"), unit: scanUnit, total: 100, count: 20,
-		start: ago, rateStart: ago,
+		start: ago, rateStart: ago, lastItem: now,
+		drawn: []drawnCount{{at: ago}},
 	}
-	content := &progress{
-		label: scanPhase("content"), total: -1,
-		waitingFor: "searching the database", start: ago, rateStart: ago,
+	load := &progress{
+		label: scanPhase("load"), total: -1,
+		waitingFor: countingRecords, start: ago, rateStart: ago,
+	}
+
+	started := now.Add(-50 * time.Second)
+	stalled := &progress{
+		label: scanPhase("hash"), unit: scanUnit, total: 100, count: 20,
+		stalledOn: hashStalledOn, start: started, rateStart: started,
+		lastItem: now.Add(-42 * time.Second),
+		drawn:    []drawnCount{{at: now.Add(-rateWindow), count: 20}},
 	}
 
 	cases := []struct {
-		p       *progress
-		room    int
-		percent bool
-		want    string
-		fits    bool
+		p    *progress
+		room int
+		bar  bool
+		want string
 	}{{
-		p: hash, room: 57, percent: true,
-		want: "[3/5] hash: [20/100] 20%, 2 files/s, elapsed 10s, eta 40s",
-		fits: true,
+		p: hash, room: 60,
+		want: "[3/4] hash: [20/100] 20%, 2 files/s, elapsed 10s, remain 40s",
 	}, {
-		p: hash, room: 56, percent: true,
-		want: "[3/5] hash: [20/100] 20%, elapsed 10s, eta 40s",
-		fits: true,
+		p: hash, room: 59,
+		want: "[3/4] hash: [20/100] 20%, elapsed 10s, remain 40s",
 	}, {
-		p: hash, room: 45, percent: true,
-		want: "[3/5] hash: [20/100] 20%, elapsed 10s, eta 40",
-		fits: false,
+		p: hash, room: 48,
+		want: "[3/4] hash: [20/100] 20%, elapsed 10s, remain 40",
 	}, {
-		// Before the library's bar, which shows the percent.
-		p: hash, room: 57, percent: false,
-		want: "[3/5] hash: [20/100], 2 files/s, elapsed 10s, eta 40s",
-		fits: true,
+		// The bar shows the percent.
+		p: hash, room: 74, bar: true,
+		want: "[3/4] hash: [20/100], 2 files/s, elapsed 10s, remain 40s" +
+			"  20% |██        |",
 	}, {
-		p: content, room: 40, percent: true,
-		want: "[5/5] content: elapsed 10s, eta unknown",
-		fits: true,
+		p: load, room: 43,
+		want: "[1/4] load: elapsed 10s, remain unknown",
+	}, {
+		p: stalled, room: 68,
+		want: "[3/4] hash: [20/100] 20%, stalled disk/db, elapsed 50s, " +
+			"remain 3m20s",
+	}, {
+		p: stalled, room: 67,
+		want: "[3/4] hash: [20/100] 20%, elapsed 50s, remain 3m20s",
 	}}
 
 	for _, tc := range cases {
-		got, fits := tc.p.line(tc.room, tc.percent)
-		if got != tc.want || fits != tc.fits {
-			t.Errorf("line(%d, %t) = %q, %t, want %q, %t",
-				tc.room, tc.percent, got, fits, tc.want, tc.fits)
+		if got := tc.p.line(now, tc.room, tc.bar); got != tc.want {
+			t.Errorf("line(%d, %t) = %q, want %q", tc.room, tc.bar, got,
+				tc.want)
 		}
 	}
 }
 
 // TestSetTotalStartsRate checks that setTotal starts a phase's rate,
-// and so its ETA, from when the total becomes known, not from when the
-// phase started waiting for it.
+// its time remaining and its time with no record read from when the
+// total becomes known, not from when the phase started waiting for it:
+// after 20 seconds of waiting for the total, the phase has not stalled 5
+// seconds after it, and has 10 seconds after it with no record read.
 func TestSetTotalStartsRate(t *testing.T) {
 	t.Parallel()
 
-	waited := time.Now().Add(-20 * time.Second)
+	clock := &testClock{now: time.Now()}
+	waited := clock.Now().Add(-20 * time.Second)
 	p := &progress{
-		label: scanPhase("load"), unit: scanUnit, total: -1, start: waited,
-		rateStart: waited,
+		now: clock.Now, label: scanPhase("load"), unit: scanUnit, total: -1,
+		stalledOn: "db", start: waited, rateStart: waited,
+		lastItem: waited, drawn: []drawnCount{{at: waited}},
 	}
 
 	p.setTotal(100)
 
-	// Ten seconds after the total came, without waiting ten seconds,
-	// 20 records are read.
-	p.start = p.start.Add(-10 * time.Second)
-	p.rateStart = p.rateStart.Add(-10 * time.Second)
-	p.count = 20
+	clock.Add(5 * time.Second)
 
-	want := "[1/5] load: [20/100] 20%, 2 files/s, elapsed 30s, eta 40s"
-	if got, _ := p.line(math.MaxInt, true); got != want {
+	want := "[1/4] load: [0/100] 0%, 0 files/s, elapsed 25s, remain unknown"
+	if got := p.line(clock.Now(), math.MaxInt, false); got != want {
+		t.Errorf("line = %q, want %q", got, want)
+	}
+
+	clock.Add(5 * time.Second)
+
+	want = "[1/4] load: [0/100] 0%, stalled db, elapsed 30s, remain unknown"
+	if got := p.line(clock.Now(), math.MaxInt, false); got != want {
+		t.Errorf("line = %q, want %q", got, want)
+	}
+
+	// Then 20 records are read.
+	for range 20 {
+		p.increment()
+	}
+
+	want = "[1/4] load: [20/100] 20%, 2 files/s, elapsed 30s, remain 40s"
+	if got := p.line(clock.Now(), math.MaxInt, false); got != want {
 		t.Errorf("line = %q, want %q", got, want)
 	}
 }
@@ -255,9 +317,9 @@ func TestPlainProgressPrintsAtStartAndEnd(t *testing.T) {
 
 	lines := strings.Split(strings.TrimSuffix(stderr(), "\n"), "\n")
 
-	want := "[3/5] hash: [0/1000] 0%, 0 files/s, elapsed 0s, eta unknown"
+	want := "[3/4] hash: [0/1000] 0%, 0 files/s, elapsed 0s, remain unknown"
 	if len(lines) != 2 || lines[0] != want ||
-		!strings.HasPrefix(lines[1], "[3/5] hash: [1000/1000] 100%, ") {
+		!strings.HasPrefix(lines[1], "[3/4] hash: [1000/1000] 100%, ") {
 		t.Errorf("stderr lines = %q, want %q, then the line at 1000",
 			lines, want)
 	}
@@ -272,13 +334,137 @@ func TestPlainProgressPrintsWhileWaiting(t *testing.T) {
 	p := startProgress(progressParams{
 		label: scanPhase("load"), total: -1,
 		waitingFor: countingRecords,
-	}, nil, testRedraw)
+	}, nil, testRedraw, time.Now)
 
 	awaitOutput(t, stderr,
-		"[1/5] load: counting the records, elapsed 0s, eta unknown\n", 3)
+		"[1/4] load: counting the records, elapsed 0s, remain unknown\n", 3)
 	p.finish()
 }
 
+// TestPlainProgressStalledProducer checks that a phase whose files stop
+// coming, as when one large file is being read or a disk is slow, goes
+// on printing its line every interval: the rate falls to 0 once no file
+// has been read for rateWindow, and once none has for stallTime the
+// line says the phase has stalled, and where it waits, in place of the
+// rate. The test moves the display's clock by hand.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestPlainProgressStalledProducer(t *testing.T) {
+	stderr := captureStderr(t)
+	clock := &testClock{now: time.Now()}
+	p := startProgress(progressParams{
+		label: scanPhase("hash"), unit: scanUnit, total: 100,
+		stalledOn: hashStalledOn,
+	}, nil, testRedraw, clock.Now)
+
+	// Pass or fail, the display ends before stderr is put back.
+	t.Cleanup(p.finish)
+
+	// 20 files read as the phase starts, then none.
+	for range 20 {
+		p.increment()
+	}
+
+	clock.Add(5 * time.Second)
+	awaitOutput(t, stderr,
+		"[3/4] hash: [20/100] 20%, 4 files/s, elapsed 5s, remain 20s\n", 3)
+
+	clock.Add(time.Second)
+	awaitOutput(t, stderr,
+		"[3/4] hash: [20/100] 20%, 0 files/s, elapsed 6s, remain 24s\n", 3)
+
+	clock.Add(4 * time.Second)
+	awaitOutput(t, stderr,
+		"[3/4] hash: [20/100] 20%, stalled disk/db, elapsed 10s, remain 40s\n",
+		3)
+}
+
+// TestPlainProgressRateAfterStall draws a phase's plain line by hand, a
+// little over plainInterval after the line before, as a late tick
+// does, through a stall and a burst of files after it: the rate covers
+// the files read since the line before, while the time remaining comes
+// from the phase's average.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestPlainProgressRateAfterStall(t *testing.T) {
+	stderr := captureStderr(t)
+	clock := &testClock{now: time.Now()}
+
+	// No timed draws: the test draws.
+	p := startProgress(progressParams{
+		label: scanPhase("hash"), unit: scanUnit, total: 1000,
+		stalledOn: hashStalledOn,
+	}, nil, time.Hour, clock.Now)
+
+	late := plainInterval + time.Millisecond
+
+	clock.Add(late)
+	p.draw()
+	clock.Add(late)
+	p.draw()
+
+	for range 100 {
+		p.increment()
+	}
+
+	clock.Add(late)
+	p.finish()
+
+	want := []string{
+		"[3/4] hash: [0/1000] 0%, 0 files/s, elapsed 0s, remain unknown",
+		"[3/4] hash: [0/1000] 0%, 0 files/s, elapsed 5s, remain unknown",
+		"[3/4] hash: [0/1000] 0%, stalled disk/db, elapsed 10s, remain unknown",
+		"[3/4] hash: [100/1000] 10%, 20 files/s, elapsed 15s, remain 2m15s",
+	}
+
+	lines := strings.Split(strings.TrimSuffix(stderr(), "\n"), "\n")
+	if !slices.Equal(lines, want) {
+		t.Errorf("stderr lines = %q, want %q", lines, want)
+	}
+}
+
+// TestProgressRateAfterStallRedrawn draws a phase by hand every
+// redrawInterval, as a terminal does, through a stall of stallTime and
+// a burst of files after it: the rate covers the files read over the
+// last rateWindow, and falls to 0 once the burst is older than that,
+// while the time remaining comes from the phase's average. Plain lines
+// show each draw.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestProgressRateAfterStallRedrawn(t *testing.T) {
+	stderr := captureStderr(t)
+	clock := &testClock{now: time.Now()}
+
+	// No timed draws: the test draws.
+	p := startProgress(progressParams{
+		label: scanPhase("hash"), unit: scanUnit, total: 1000,
+		stalledOn: hashStalledOn,
+	}, nil, time.Hour, clock.Now)
+
+	// redraw draws the display every redrawInterval for d.
+	redraw := func(d time.Duration) {
+		for range d / redrawInterval {
+			clock.Add(redrawInterval)
+			p.draw()
+		}
+	}
+
+	redraw(stallTime)
+
+	for range 50 {
+		p.increment()
+	}
+
+	redraw(rateWindow + redrawInterval)
+	p.finish()
+
+	want := "[3/4] hash: [50/1000] 5%, 10 files/s, elapsed 15s, remain 4m45s\n" +
+		"[3/4] hash: [50/1000] 5%, 0 files/s, elapsed 15s, remain 4m47s\n"
+	if !strings.Contains(stderr(), want) {
+		t.Errorf("stderr = %q, want the lines %q", stderr(), want)
+	}
+}
+
 // lastFrame returns what a terminal shows of the frames a display drew:
 // the last one. The library starts each frame with a carriage return
 // and erases the previous one with spaces first.
@@ -295,10 +481,10 @@ func lastFrame(out string) string {
 }
 
 // TestTerminalRedrawsWhileWaiting checks that the terminal display of a
-// phase, spinner or bar, keeps being drawn while the phase waits for its
-// next item, with the elapsed time as of now, and shows every item
-// completed before the wait. stderr is not a terminal here, so the
-// displays take it to be fallbackWidth wide.
+// phase, with a bar or without, keeps being drawn while the phase waits
+// for its next item, with the elapsed time as of now, and shows every
+// item completed before the wait. The terminal is 120 columns wide, so
+// the hash phase's display has room for its bar.
 //
 //nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
 func TestTerminalRedrawsWhileWaiting(t *testing.T) {
@@ -321,7 +507,8 @@ func TestTerminalRedrawsWhileWaiting(t *testing.T) {
 	for _, tc := range cases {
 		before := len(stderr())
 		since := func() string { return stderr()[before:] }
-		p := startProgress(tc.params, terminalWidth, testRedraw)
+		p := startProgress(tc.params, func() int { return 120 }, testRedraw,
+			time.Now)
 
 		for range 50 {
 			p.increment()
@@ -343,21 +530,23 @@ func TestTerminalRedrawsWhileWaiting(t *testing.T) {
 
 // drawLate draws the display params describes on a terminal width
 // columns wide as it starts and once more as it ends, with count items
-// done two and a half hours into the phase, and returns what it wrote
-// to stderr.
+// done two and a half hours into the phase, the last just now, and
+// returns what it wrote to stderr.
 func drawLate(stderr func() string, params progressParams, width int,
 	count int64,
 ) string {
 	before := len(stderr())
+	clock := &testClock{now: time.Now()}
 
 	// No timed draws come between the two.
-	p := startProgress(params, func() int { return width }, time.Hour)
+	p := startProgress(params, func() int { return width }, time.Hour,
+		clock.Now)
 
 	// Without counting the items one by one or waiting the hours.
+	clock.Add(150 * time.Minute)
+
 	p.mu.Lock()
-	p.count = count
-	p.start = p.start.Add(-150 * time.Minute)
-	p.rateStart = p.start
+	p.count, p.lastItem = count, clock.Now()
 	p.mu.Unlock()
 
 	p.finish()
@@ -365,13 +554,13 @@ func drawLate(stderr func() string, params progressParams, width int,
 	return stderr()[before:]
 }
 
-// TestTerminalLinesKeepETA checks the line each display shows on an
-// 80-column terminal at a large scan's counts and times, and the line
-// of trees' read phase at the same counts: the rate is left out, so
-// that the elapsed time and the ETA stay whole.
+// TestTerminalLinesKeepTimeRemaining checks the line each display shows
+// on an 80-column terminal at a large scan's counts and times, and the
+// line of trees' read phase at the same counts: the rate is left out,
+// so that the elapsed time and the time remaining stay whole.
 //
 //nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
-func TestTerminalLinesKeepETA(t *testing.T) {
+func TestTerminalLinesKeepTimeRemaining(t *testing.T) {
 	stderr := captureStderr(t)
 
 	cases := []struct {
@@ -383,26 +572,20 @@ func TestTerminalLinesKeepETA(t *testing.T) {
 			label: scanPhase("walk"), unit: scanUnit, total: 1200000,
 			estimate: true,
 		},
-		want: "[2/5] walk: [1234567/~1200000] 103%, elapsed 2h30m0s, " +
-			"eta unknown",
+		want: "[2/4] walk: [1234567/~1200000] 103%, elapsed 2h30m0s, " +
+			"remain unknown",
 	}, {
 		params: progressParams{
 			label: scanPhase("hash"), unit: scanUnit, total: 9876543,
 		},
-		want: "[3/5] hash: [1234567/9876543] 12%, elapsed 2h30m0s, " +
-			"eta 17h30m0s",
-	}, {
-		params: progressParams{
-			label: scanPhase("content"), unit: scanUnit, total: 9876543,
-		},
-		want: "[5/5] content: [1234567/9876543] 12%, elapsed 2h30m0s, " +
-			"eta 17h30m0s",
+		want: "[3/4] hash: [1234567/9876543] 12%, elapsed 2h30m0s, " +
+			"remain 17h30m0s",
 	}, {
 		params: progressParams{
 			label: treesPhase("read"), unit: "records", total: 9876543,
 		},
 		want: "[2/4] read: [1234567/9876543] 12%, elapsed 2h30m0s, " +
-			"eta 17h30m0s",
+			"remain 17h30m0s",
 	}}
 
 	for _, tc := range cases {
@@ -413,6 +596,87 @@ func TestTerminalLinesKeepETA(t *testing.T) {
 	}
 }
 
+// TestTerminalStalledLines draws every phase's line once the phase has
+// stalled, its last item done 42 seconds before. At an ordinary scan's
+// counts and times, 12345 of 45678 items done four and a half minutes
+// in, on a terminal 100 columns wide, the line shows where the phase
+// waits whole, beside the phase, progress, elapsed time and time
+// remaining. At a large scan's, 1234567 of 9876543 two and a half hours
+// in, on an 80-column terminal, those four still show whole, as the
+// words give way first where they do not fit.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalStalledLines(t *testing.T) {
+	stderr := captureStderr(t)
+
+	// drawStalled draws the display params describes on a terminal width
+	// columns wide as it starts and once more as it ends, with count of
+	// total items done elapsed into the phase, and returns what the
+	// terminal shows.
+	drawStalled := func(params progressParams, width int, total,
+		count int64, elapsed time.Duration,
+	) string {
+		before := len(stderr())
+		clock := &testClock{now: time.Now()}
+		params.total = total
+
+		// No timed draws come between the two.
+		p := startProgress(params, func() int { return width }, time.Hour,
+			clock.Now)
+
+		clock.Add(elapsed - 42*time.Second)
+
+		p.mu.Lock()
+		p.count, p.lastItem = count, clock.Now()
+		p.mu.Unlock()
+
+		clock.Add(42 * time.Second)
+		p.finish()
+
+		return lastFrame(stderr()[before:])
+	}
+
+	phases := []progressParams{
+		{label: scanPhase("load"), stalledOn: "db"},
+		{label: scanPhase("walk"), estimate: true, stalledOn: "disk"},
+		{label: scanPhase("hash"), stalledOn: hashStalledOn},
+		{label: scanPhase("update"), stalledOn: "db"},
+		{label: treesPhase("read"), stalledOn: "db"},
+		{label: treesPhase("group"), stalledOn: "cpu"},
+		{label: treesPhase("write"), stalledOn: "out"},
+		{label: reportPhase("read"), stalledOn: "db/out"},
+	}
+
+	for _, params := range phases {
+		approx := ""
+		if params.estimate {
+			approx = "~"
+		}
+
+		// The percent is in the line, or beside the bar.
+		shown := drawStalled(params, 100, 45678, 12345,
+			4*time.Minute+30*time.Second)
+		for _, want := range []string{
+			params.label + ": [12345/" + approx + "45678]",
+			", stalled " + params.stalledOn + ", elapsed 4m30s, remain 12m9s",
+		} {
+			if !strings.Contains(shown, want) {
+				t.Errorf("terminal shows %q, want %q", shown, want)
+			}
+		}
+
+		shown = drawStalled(params, 80, 9876543, 1234567, 150*time.Minute)
+		for _, want := range []string{
+			params.label + ": [1234567/" + approx + "9876543] 12%, ",
+			", elapsed 2h30m0s, remain 17h30m0s",
+		} {
+			if !strings.Contains(shown, want) {
+				t.Errorf("terminal shows %q, want %q", shown, want)
+			}
+		}
+	}
+}
+
 // TestTerminalLinesFitWidth draws a large scan's bar display and a small
 // scan's, two and a half hours into the phase, on terminals from 120
 // columns down to 40, and checks that every line stays clear of the
@@ -427,7 +691,7 @@ func TestTerminalLinesFitWidth(t *testing.T) {
 	for _, width := range []int{120, 100, 80, 72, 60, 50, 40} {
 		for _, total := range []int64{9876543, 20000} {
 			params := progressParams{
-				label: scanPhase("content"), unit: scanUnit, total: total,
+				label: scanPhase("update"), unit: scanUnit, total: total,
 			}
 			out := drawLate(stderr, params, width, total/8)
 
@@ -449,13 +713,164 @@ func TestTerminalLinesFitWidth(t *testing.T) {
 	}
 }
 
+// TestTerminalLinesStartWithSpinner draws a display with no total and
+// one with a bar, two and a half hours into the phase, on a terminal 120
+// columns wide. Each line must start with the library's spinner in the
+// first column, then a space and the phase's label.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalLinesStartWithSpinner(t *testing.T) {
+	stderr := captureStderr(t)
+
+	for _, params := range []progressParams{
+		{label: scanPhase("walk"), unit: scanUnit, total: -1},
+		{label: scanPhase("hash"), unit: scanUnit, total: 9876543},
+	} {
+		shown := lastFrame(drawLate(stderr, params, 120, 1234567))
+		spinner, rest, _ := strings.Cut(shown, " ")
+
+		if utf8.RuneCountInString(spinner) != 1 ||
+			!strings.HasPrefix(rest, params.label+": ") {
+			t.Errorf("terminal shows %q, want the spinner, a space and %q",
+				shown, params.label)
+		}
+
+		if params.total > 0 && !strings.Contains(shown, "% |") {
+			t.Errorf("terminal shows %q, want a bar", shown)
+		}
+	}
+}
+
+// TestTerminalBarStaysAtRightEdge draws the hash phase's display two
+// and a half hours in, at two counts whose lines differ in length, on
+// terminals 110 and 120 columns wide. The bar is partly filled at the
+// first count and full at the second. It must start the same number of
+// columns from the terminal's right edge each time, and end the same
+// number of columns from it: a line that grows or shrinks, as its time
+// remaining does, never moves the bar, and nor do the bar's filled
+// cells.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalBarStaysAtRightEdge(t *testing.T) {
+	stderr := captureStderr(t)
+	params := progressParams{
+		label: scanPhase("hash"), unit: scanUnit, total: 9876543,
+	}
+
+	widths := []int{110, 120}
+	counts := []int64{1234567, 9876543}
+	startFromEdge := make([]int, 0, len(widths)*len(counts))
+	endFromEdge := make([]int, 0, len(widths)*len(counts))
+
+	for _, width := range widths {
+		for _, count := range counts {
+			shown := lastFrame(drawLate(stderr, params, width, count))
+
+			beforeBar, _, found := strings.Cut(shown, "% |")
+			if !found {
+				t.Fatalf("terminal %d wide shows %q, want a bar", width, shown)
+			}
+
+			// The bar ends with the last "|".
+			throughBar := shown[:strings.LastIndex(shown, "|")+1]
+
+			startFromEdge = append(startFromEdge,
+				width-utf8.RuneCountInString(beforeBar))
+			endFromEdge = append(endFromEdge,
+				width-utf8.RuneCountInString(throughBar))
+		}
+	}
+
+	if slices.Min(startFromEdge) != slices.Max(startFromEdge) {
+		t.Errorf("bar starts %v columns from the right edge, want the same "+
+			"every time", startFromEdge)
+	}
+
+	if slices.Min(endFromEdge) != slices.Max(endFromEdge) {
+		t.Errorf("bar ends %v columns from the right edge, want the same "+
+			"every time", endFromEdge)
+	}
+}
+
+// TestTerminalRateGivesWayBeforeBar draws the hash phase's display two
+// and a half hours in. On a terminal 90 columns wide the line fits
+// beside the bar without its rate, but not with it: the bar is drawn
+// and the rate is not. On a terminal 85 columns wide the line does not
+// fit beside the bar even without its rate: neither is drawn, though
+// the rate would fit where the bar was.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalRateGivesWayBeforeBar(t *testing.T) {
+	stderr := captureStderr(t)
+	params := progressParams{
+		label: scanPhase("hash"), unit: scanUnit, total: 9876543,
+	}
+
+	shown := lastFrame(drawLate(stderr, params, 90, 1234567))
+	if !strings.Contains(shown, "% |") || strings.Contains(shown, "files/s") {
+		t.Errorf("terminal 90 wide shows %q, want the bar and no rate", shown)
+	}
+
+	shown = lastFrame(drawLate(stderr, params, 85, 1234567))
+	if strings.Contains(shown, "% |") || strings.Contains(shown, "files/s") {
+		t.Errorf("terminal 85 wide shows %q, want neither bar nor rate", shown)
+	}
+}
+
+// TestTerminalSpinnerTurnsBesideBar draws the hash phase's display, its
+// bar partly filled, several times on a terminal 120 columns wide. The
+// spinner must turn at every draw. A filled cell of the bar takes one
+// column but three bytes. A line measured in bytes would seem too wide
+// for the terminal, and every draw would start the display over, its
+// spinner included.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestTerminalSpinnerTurnsBesideBar(t *testing.T) {
+	stderr := captureStderr(t)
+	params := progressParams{
+		label: scanPhase("hash"), unit: scanUnit, total: 9876543,
+	}
+
+	// No timed draws: the test draws.
+	p := startProgress(params, func() int { return 120 }, time.Hour,
+		time.Now)
+
+	p.mu.Lock()
+	p.count = 1234567
+	p.mu.Unlock()
+
+	const draws = 4
+
+	spinners := make([]string, 0, draws)
+
+	for range draws {
+		before := len(stderr())
+
+		p.draw()
+
+		spinner, _, _ := strings.Cut(lastFrame(stderr()[before:]), " ")
+		spinners = append(spinners, spinner)
+	}
+
+	p.finish()
+
+	for i := 1; i < len(spinners); i++ {
+		if spinners[i] == spinners[i-1] {
+			t.Errorf("spinners at successive draws are %q, want each to "+
+				"differ from the one before", spinners)
+
+			break
+		}
+	}
+}
+
 // TestTerminalNarrowedRedrawsInPlace draws a large scan's display, two
 // and a half hours into the phase, on a terminal 120 columns wide, then
 // makes the terminal narrower than that line and draws it again a few
 // times. Nothing written after that, the erase before each redraw
 // included, may reach the narrower terminal's last column: it would
-// wrap, and every redraw would leave a line behind. At these widths the
-// spinner stays a spinner and the bar stays a bar.
+// wrap, and every redraw would leave a line behind. At the narrower
+// width the hash phase's bar gives way.
 //
 //nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
 func TestTerminalNarrowedRedrawsInPlace(t *testing.T) {
@@ -473,20 +888,22 @@ func TestTerminalNarrowedRedrawsInPlace(t *testing.T) {
 			progressParams{
 				label: scanPhase("hash"), unit: scanUnit, total: 9876543,
 			},
-			90,
+			80,
 		},
 	}
 
 	for _, tc := range cases {
 		width := 120
+		clock := &testClock{now: time.Now()}
 
 		// No timed draws: the test draws.
-		p := startProgress(tc.params, func() int { return width }, time.Hour)
+		p := startProgress(tc.params, func() int { return width }, time.Hour,
+			clock.Now)
+
+		clock.Add(150 * time.Minute)
 
 		p.mu.Lock()
-		p.count = 1234567
-		p.start = p.start.Add(-150 * time.Minute)
-		p.rateStart = p.start
+		p.count, p.lastItem = 1234567, clock.Now()
 		p.mu.Unlock()
 
 		p.draw()
@@ -511,10 +928,10 @@ func TestTerminalNarrowedRedrawsInPlace(t *testing.T) {
 	}
 }
 
-// TestProgressWarningsOnOwnLines drives the terminal displays, spinner
-// and bar, through a run of warnings with no items between them, as when
-// the walk meets many unreadable paths, for many redraws: every warning
-// must land on a line of its own, never inside a redraw.
+// TestProgressWarningsOnOwnLines drives the terminal displays, with a
+// bar and without, through a run of warnings with no items between
+// them, as when the walk meets many unreadable paths, for many redraws:
+// every warning must land on a line of its own, never inside a redraw.
 //
 //nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
 func TestProgressWarningsOnOwnLines(t *testing.T) {
@@ -528,7 +945,7 @@ func TestProgressWarningsOnOwnLines(t *testing.T) {
 	issued := 0
 
 	for _, params := range cases {
-		p := startProgress(params, terminalWidth, testRedraw)
+		p := startProgress(params, terminalWidth, testRedraw, time.Now)
 
 		// No pause between warnings: one written straight to stderr is
 		// garbled only if a redraw lands while it is being written.
@@ -560,11 +977,12 @@ func TestProgressWarningsOnOwnLines(t *testing.T) {
 	}
 }
 
-// TestProgressWriterRowsOnOwnLines drives the terminal displays,
-// spinner and bar, through a run of rows written through the display's
+// TestProgressWriterRowsOnOwnLines drives the terminal displays, with a
+// bar and without, through a run of rows written through the display's
 // writer to the same terminal, as stdout is in a plain "sfdupes trees",
 // each written out at once, for many redraws: the terminal must show
-// every row whole, in order, on a line of its own.
+// every row whole, in order, on a line of its own. The terminal is 120
+// columns wide, so the write phase's display has room for its bar.
 //
 //nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
 func TestProgressWriterRowsOnOwnLines(t *testing.T) {
@@ -581,7 +999,8 @@ func TestProgressWriterRowsOnOwnLines(t *testing.T) {
 	var want []string
 
 	for _, params := range cases {
-		p := startProgress(params, terminalWidth, testRedraw)
+		p := startProgress(params, func() int { return 120 }, testRedraw,
+			time.Now)
 		out := p.writer(os.Stderr)
 
 		// No pause between rows: one is garbled only if a redraw lands
@@ -644,7 +1063,7 @@ func TestProgressWriterStalledStdoutKeepsLines(t *testing.T) {
 	})
 
 	p := startProgress(progressParams{label: treesPhase("write"), total: 1},
-		nil, testRedraw)
+		nil, testRedraw, time.Now)
 	out := p.writer(w)
 	written := make(chan error, 1)
 
@@ -687,7 +1106,7 @@ func TestProgressWriterStalledStdoutKeepsLines(t *testing.T) {
 func TestTerminalStoppedShortKeepsCount(t *testing.T) {
 	stderr := captureStderr(t)
 	p := startProgress(progressParams{label: scanPhase("hash"), total: 10},
-		terminalWidth, redrawInterval)
+		terminalWidth, redrawInterval, time.Now)
 
 	p.increment()
 	p.increment()
@@ -706,7 +1125,7 @@ func TestTerminalStoppedShortKeepsCount(t *testing.T) {
 func TestWarningAfterLastItemKeepsBar(t *testing.T) {
 	stderr := captureStderr(t)
 	p := startProgress(progressParams{label: scanPhase("hash"), total: 2},
-		terminalWidth, testRedraw)
+		terminalWidth, testRedraw, time.Now)
 
 	p.increment()
 	p.increment()

report.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"crypto/sha256"
 	"database/sql"
 	"fmt"
 	"io"
@@ -24,9 +25,9 @@ const minGroupSize = 2
 type scanRec struct {
 	size    int64
 	mtime   time.Time
-	head    string
-	tail    string
-	content string
+	head    [sha256.Size]byte
+	tail    [sha256.Size]byte
+	content [sha256.Size]byte
 	path    string
 }
 
@@ -74,9 +75,11 @@ func runReport(ctx context.Context, stdout io.Writer) error {
 
 	defer func() { _ = db.Close() }()
 
+	// The read phase writes the report to stdout while it reads the
+	// records, so it may wait on either.
 	prog = newProgress(progressParams{
 		label: reportPhase("read"), unit: "records", total: -1,
-		waitingFor: countingRecords,
+		waitingFor: countingRecords, stalledOn: "db/out",
 	})
 	report, err := readReport(ctx, db, dbPath, stdout, prog)
 
@@ -167,12 +170,6 @@ type reportWriter struct {
 func (w *reportWriter) add(r scanRec) error {
 	w.records++
 
-	// A record without a content hash has unknown content (README
-	// "Database"), so it is never a duplicate.
-	if r.content == "" {
-		return nil
-	}
-
 	if r.size == w.sig.size && r.head == w.sig.head &&
 		r.tail == w.sig.tail && r.content == w.sig.content {
 		w.paths = append(w.paths, r.path)

report_test.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"bytes"
+	"crypto/sha256"
 	"database/sql"
 	"errors"
 	"fmt"
@@ -18,14 +19,27 @@ import (
 // awkwardDir is a directory name holding every byte the reports escape.
 const awkwardDir = "/d/\tone\ntwo\rthree\\four"
 
+// testHash returns a stand-in hash for a test record: the bytes of s,
+// then zeros. Stand-ins sort as their strings do, so a test can choose
+// the order in which report reads its records.
+func testHash(s string) [sha256.Size]byte {
+	var h [sha256.Size]byte
+
+	copy(h[:], s)
+
+	return h
+}
+
 // awkwardPairRecs is a duplicate pair in sibling directories /d/A and
 // awkwardDir. A raw tab sorts before "A" but its escaped form `\t`
 // sorts after it, so awkwardDir coming first shows that sorting uses
 // the raw path.
 func awkwardPairRecs() []scanRec {
+	h, tl, c := testHash("h"), testHash("t"), testHash("c")
+
 	return []scanRec{
-		{size: 5, head: "h", tail: "t", content: "c", path: "/d/A/f"},
-		{size: 5, head: "h", tail: "t", content: "c", path: awkwardDir + "/f"},
+		{size: 5, head: h, tail: tl, content: c, path: "/d/A/f"},
+		{size: 5, head: h, tail: tl, content: c, path: awkwardDir + "/f"},
 	}
 }
 
@@ -143,8 +157,8 @@ func TestReportStdoutFailsWhileReading(t *testing.T) {
 	recs := make([]scanRec, 2*ioBufSize/len(dir))
 	for i := range recs {
 		recs[i] = scanRec{
-			size: int64(i/2) + 1, head: "h", tail: "t", content: "c",
-			path: fmt.Sprintf("%s/%d", dir, i),
+			size: int64(i/2) + 1, head: testHash("h"), tail: testHash("t"),
+			content: testHash("c"), path: fmt.Sprintf("%s/%d", dir, i),
 		}
 	}
 
@@ -156,7 +170,7 @@ func TestReportStdoutFailsWhileReading(t *testing.T) {
 	}
 
 	// Counts the records read, and draws nothing.
-	prog := &progress{}
+	prog := &progress{now: time.Now}
 
 	_, err = readReport(t.Context(), db, "", failingWriter{}, prog)
 	if !errors.Is(err, errWriteFailed) ||
@@ -173,7 +187,7 @@ func TestReportStdoutFailsWhileReading(t *testing.T) {
 // reportOpenLine is the plain line of report's open phase when it opens
 // the database at once; it prints it as the phase starts and as it ends.
 const reportOpenLine = "[1/2] open: opening the database, elapsed 0s, " +
-	"eta unknown"
+	"remain unknown"
 
 // smokeReport is report's stdout for the smoke-test records.
 const smokeReport = "first\tdupe\tsize\n" +
@@ -211,7 +225,7 @@ func TestRunReportProgressNamesEachPhase(t *testing.T) {
 		"report: database " + path + " (from " + databaseEnv + ")",
 		reportOpenLine,
 		reportOpenLine,
-		"[2/2] read: counting the records, elapsed 0s, eta unknown",
+		"[2/2] read: counting the records, elapsed 0s, remain unknown",
 		"[2/2] read: [6/6] 100%, ",
 		"report: 6 records read, 2 duplicate groups, 4 dupe files, " +
 			"6.1 KiB reclaimable",
@@ -250,7 +264,7 @@ func TestReadReportOnTerminal(t *testing.T) {
 	p := startProgress(progressParams{
 		label: reportPhase("read"), unit: "records", total: -1,
 		waitingFor: countingRecords,
-	}, terminalWidth, time.Hour)
+	}, terminalWidth, time.Hour, time.Now)
 
 	_, err = readReport(t.Context(), db, "", os.Stderr, p)
 
@@ -277,13 +291,14 @@ func TestReadReportOnTerminal(t *testing.T) {
 func TestRunReportsIgnoreInsertionOrder(t *testing.T) {
 	// README §Constraints: identical database contents give identical
 	// output, whatever order the records were inserted in.
+	a, b := testHash("a"), testHash("b")
+
 	recs := append(smokeTreeRecs(), awkwardPairRecs()...)
 	recs = append(recs,
-		scanRec{size: 50, head: "b", tail: "b", content: "b", path: "/y/2"},
-		scanRec{size: 50, head: "b", tail: "b", content: "b", path: "/y/1"},
-		scanRec{size: 50, head: "a", tail: "a", content: "a", path: "/x/2"},
-		scanRec{size: 50, head: "a", tail: "a", content: "a", path: "/x/1"},
-		scanRec{size: 50, path: "/x/unhashed"},
+		scanRec{size: 50, head: b, tail: b, content: b, path: "/y/2"},
+		scanRec{size: 50, head: b, tail: b, content: b, path: "/y/1"},
+		scanRec{size: 50, head: a, tail: a, content: a, path: "/x/2"},
+		scanRec{size: 50, head: a, tail: a, content: a, path: "/x/1"},
 	)
 
 	reversed := slices.Clone(recs)
@@ -386,16 +401,19 @@ func TestWarnfEscapes(t *testing.T) {
 func TestDupeGroups(t *testing.T) {
 	t.Parallel()
 
+	h, tl, c := testHash("h"), testHash("t"), testHash("c")
+	bigH, bigT, bigC := testHash("H"), testHash("T"), testHash("C")
+	u := testHash("u")
 	recs := []scanRec{
-		{size: 100, head: "h", tail: "t", content: "c", path: "/z/b"},
-		{size: 100, head: "h", tail: "t", content: "c", path: "/z/a"},
-		{size: 100, head: "h", tail: "t", content: "c", path: "/z/c"},
-		{size: 4000, head: "H", tail: "T", content: "C", path: "/big/2"},
-		{size: 4000, head: "H", tail: "T", content: "C", path: "/big/1"},
+		{size: 100, head: h, tail: tl, content: c, path: "/z/b"},
+		{size: 100, head: h, tail: tl, content: c, path: "/z/a"},
+		{size: 100, head: h, tail: tl, content: c, path: "/z/c"},
+		{size: 4000, head: bigH, tail: bigT, content: bigC, path: "/big/2"},
+		{size: 4000, head: bigH, tail: bigT, content: bigC, path: "/big/1"},
 		// Same size as the /z group but a different head hash.
-		{size: 100, head: "other", tail: "t", content: "c", path: "/z/d"},
+		{size: 100, head: testHash("other"), tail: tl, content: c, path: "/z/d"},
 		// A singleton signature must not form a group.
-		{size: 7, head: "u", tail: "u", content: "u", path: "/lonely"},
+		{size: 7, head: u, tail: u, content: u, path: "/lonely"},
 	}
 
 	groups := dupeGroupsOf(t, recs)
@@ -419,16 +437,13 @@ func TestDupeGroups(t *testing.T) {
 func TestDupeGroupsContentSeparates(t *testing.T) {
 	t.Parallel()
 
-	// Same size, head, and tail, but different content hashes: the final
-	// rung keeps them apart, so no group forms. Matching content groups.
-	// Records without a content hash never group, not even with each
-	// other.
+	// Same size, head, and tail: /b differs from the others only in its
+	// content hash, so it joins no group, while /a and /c group.
+	h, tl := testHash("h"), testHash("t")
 	recs := []scanRec{
-		{size: 100, head: "h", tail: "t", content: "c1", path: "/a"},
-		{size: 100, head: "h", tail: "t", content: "c2", path: "/b"},
-		{size: 100, head: "h", tail: "t", content: "c1", path: "/c"},
-		{size: 100, head: "h", tail: "t", path: "/d"},
-		{size: 100, head: "h", tail: "t", path: "/e"},
+		{size: 100, head: h, tail: tl, content: testHash("c1"), path: "/a"},
+		{size: 100, head: h, tail: tl, content: testHash("c2"), path: "/b"},
+		{size: 100, head: h, tail: tl, content: testHash("c1"), path: "/c"},
 	}
 
 	groups := dupeGroupsOf(t, recs)
@@ -447,14 +462,15 @@ func TestDupeGroupsMtimeExcluded(t *testing.T) {
 
 	// mtime is informational only; records differing only in mtime
 	// still group together.
+	h, tl, c := testHash("h"), testHash("t"), testHash("c")
 	recs := []scanRec{
 		{
-			size: 9, mtime: time.Unix(100, 0), head: "h", tail: "t",
-			content: "c", path: "/m/1",
+			size: 9, mtime: time.Unix(100, 0), head: h, tail: tl,
+			content: c, path: "/m/1",
 		},
 		{
-			size: 9, mtime: time.Unix(200, 0), head: "h", tail: "t",
-			content: "c", path: "/m/2",
+			size: 9, mtime: time.Unix(200, 0), head: h, tail: tl,
+			content: c, path: "/m/2",
 		},
 	}
 
@@ -469,11 +485,12 @@ func TestDupeGroupsTieBreak(t *testing.T) {
 
 	// The hashes sort opposite to the first paths, so ordering the
 	// groups by hash instead of by first path fails this test.
+	a, b := testHash("a"), testHash("b")
 	recs := []scanRec{
-		{size: 50, head: "a", tail: "a", content: "a", path: "/beta/2"},
-		{size: 50, head: "a", tail: "a", content: "a", path: "/beta/1"},
-		{size: 50, head: "b", tail: "b", content: "b", path: "/alpha/2"},
-		{size: 50, head: "b", tail: "b", content: "b", path: "/alpha/1"},
+		{size: 50, head: a, tail: a, content: a, path: "/beta/2"},
+		{size: 50, head: a, tail: a, content: a, path: "/beta/1"},
+		{size: 50, head: b, tail: b, content: b, path: "/alpha/2"},
+		{size: 50, head: b, tail: b, content: b, path: "/alpha/1"},
 	}
 
 	groups := dupeGroupsOf(t, recs)
@@ -495,15 +512,16 @@ func TestDupeGroupsOrderedByFirstPath(t *testing.T) {
 	// /z, /k, which is neither the order of their first paths nor its
 	// reverse, and must write them ordered by first path. The group of
 	// size 7 comes after them all, though its first path sorts first.
+	a, b, c, d := testHash("a"), testHash("b"), testHash("c"), testHash("d")
 	recs := []scanRec{
-		{size: 50, head: "a", tail: "a", content: "a", path: "/k/2"},
-		{size: 50, head: "a", tail: "a", content: "a", path: "/k/1"},
-		{size: 50, head: "b", tail: "b", content: "b", path: "/z/1"},
-		{size: 50, head: "b", tail: "b", content: "b", path: "/z/2"},
-		{size: 50, head: "c", tail: "c", content: "c", path: "/a/2"},
-		{size: 50, head: "c", tail: "c", content: "c", path: "/a/1"},
-		{size: 7, head: "d", tail: "d", content: "d", path: "/0/2"},
-		{size: 7, head: "d", tail: "d", content: "d", path: "/0/1"},
+		{size: 50, head: a, tail: a, content: a, path: "/k/2"},
+		{size: 50, head: a, tail: a, content: a, path: "/k/1"},
+		{size: 50, head: b, tail: b, content: b, path: "/z/1"},
+		{size: 50, head: b, tail: b, content: b, path: "/z/2"},
+		{size: 50, head: c, tail: c, content: c, path: "/a/2"},
+		{size: 50, head: c, tail: c, content: c, path: "/a/1"},
+		{size: 7, head: d, tail: d, content: d, path: "/0/2"},
+		{size: 7, head: d, tail: d, content: d, path: "/0/1"},
 	}
 
 	groups := dupeGroupsOf(t, recs)
@@ -522,11 +540,12 @@ func TestDupeGroupsOrderedByFirstPath(t *testing.T) {
 func TestDupeGroupsDeterministic(t *testing.T) {
 	t.Parallel()
 
+	a, b := testHash("a"), testHash("b")
 	recs := []scanRec{
-		{size: 1, head: "a", tail: "a", content: "a", path: "/p/1"},
-		{size: 1, head: "a", tail: "a", content: "a", path: "/p/2"},
-		{size: 2, head: "b", tail: "b", content: "b", path: "/q/1"},
-		{size: 2, head: "b", tail: "b", content: "b", path: "/q/2"},
+		{size: 1, head: a, tail: a, content: a, path: "/p/1"},
+		{size: 1, head: a, tail: a, content: a, path: "/p/2"},
+		{size: 2, head: b, tail: b, content: b, path: "/q/1"},
+		{size: 2, head: b, tail: b, content: b, path: "/q/2"},
 	}
 
 	forward := dupeGroupsOf(t, recs)

script/cibuild

@@ -2,11 +2,12 @@
 # script/cibuild: run the CI build. It bootstraps first: a CI runner
 # checks out and runs this and nothing else, and script/fmt-check runs
 # the formatter on the host, which a pristine checkout cannot do.
-# A new CACHEBUST value reruns every RUN step, since a cached gate phase
-# is a check that did not run; unlike --no-cache, it keeps Go's build cache.
+# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
+# line, since a cached gate phase is a check that did not run; unlike
+# --no-cache, it keeps the layers above that line and the cache mounts.
 # This relies on every stage of the Dockerfile declaring ARG CACHEBUST
-# first; a stage without that line is served from cache on an unchanged
-# tree, with no warning.
+# before every step that lints, tests or compiles; a stage without that
+# line is served from cache on an unchanged tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/docker

@@ -1,11 +1,12 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
 # Identical in all repos; the tag comes from script/projectname.
-# A new CACHEBUST value reruns every RUN step, since a cached gate phase
-# is a check that did not run; unlike --no-cache, it keeps Go's build cache.
+# A new CACHEBUST value reruns every RUN step after the ARG CACHEBUST
+# line, since a cached gate phase is a check that did not run; unlike
+# --no-cache, it keeps the layers above that line and the cache mounts.
 # This relies on every stage of the Dockerfile declaring ARG CACHEBUST
-# first; a stage without that line is served from cache on an unchanged
-# tree, with no warning.
+# before every step that lints, tests or compiles; a stage without that
+# line is served from cache on an unchanged tree, with no warning.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/lint

@@ -5,11 +5,13 @@
 # make its answer untrustworthy.
 #
 # The phase is not the last stage in the file, so it is built only when
-# --target names it. A new CACHEBUST value reruns every RUN step, since
-# a cached lint layer is a lint that did not run; unlike --no-cache, it
-# keeps Go's build cache. This relies on every stage of the Dockerfile
-# declaring ARG CACHEBUST first; a stage without that line is served
-# from cache on an unchanged tree, with no warning.
+# --target names it. A new CACHEBUST value reruns every RUN step after
+# the ARG CACHEBUST line, since a cached lint layer is a lint that did
+# not run; unlike --no-cache, it keeps the layers above that line and
+# the cache mounts. This relies on every stage of the Dockerfile
+# declaring ARG CACHEBUST before every step that lints, tests or
+# compiles; a stage without that line is served from cache on an
+# unchanged tree, with no warning.
 # --output type=cacheonly writes no image, since nothing uses one.
 set -eu
 

script/test

@@ -3,11 +3,12 @@
 # and this builds that phase alone, on the same terms as script/lint:
 # --target because a phase that is not the last stage is built only when
 # named, and a new CACHEBUST value because a cached test layer is a test
-# that did not run; unlike --no-cache, it keeps Go's build cache. This
-# relies on every stage of the Dockerfile declaring ARG CACHEBUST first;
-# a stage without that line is served from cache on an unchanged tree,
-# with no warning. --output type=cacheonly writes no image, since
-# nothing uses one.
+# that did not run; unlike --no-cache, it keeps the layers above the ARG
+# CACHEBUST line and the cache mounts. This relies on every stage of the
+# Dockerfile declaring ARG CACHEBUST before every step that lints, tests
+# or compiles; a stage without that line is served from cache on an
+# unchanged tree, with no warning. --output type=cacheonly writes no
+# image, since nothing uses one.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

trees.go

@@ -72,7 +72,7 @@ func runTrees(ctx context.Context, stdout io.Writer) error {
 
 	prog = newProgress(progressParams{
 		label: treesPhase("read"), unit: "records", total: -1,
-		waitingFor: countingRecords,
+		waitingFor: countingRecords, stalledOn: "db",
 	})
 	records, super, allDirs, err := readTree(ctx, db, prog)
 
@@ -82,9 +82,11 @@ func runTrees(ctx context.Context, stdout io.Writer) error {
 		return fmt.Errorf("database %s: %w", dbPath, err)
 	}
 
+	// Grouping works in memory, so it waits on nothing but the
+	// processor.
 	prog = newProgress(progressParams{
 		label: treesPhase("group"), unit: "directories",
-		total: int64(len(allDirs)),
+		total: int64(len(allDirs)), stalledOn: "cpu",
 	})
 	dupes := collectTreeGroups(allDirs, super, prog)
 
@@ -92,6 +94,7 @@ func runTrees(ctx context.Context, stdout io.Writer) error {
 
 	prog = newProgress(progressParams{
 		label: treesPhase("write"), unit: "groups", total: int64(len(dupes)),
+		stalledOn: "out",
 	})
 	dupeTrees, reclaimable, err := writeTreeGroups(stdout, dupes, prog)
 
@@ -283,18 +286,9 @@ func (b *treeBuilder) finish() (*treeNode, []*treeNode) {
 // name and its signature (size, head, tail, content); mtime is
 // excluded.
 func fileEntry(name string, r scanRec) string {
-	content := r.content
-
-	// A record without a content hash has unknown content (README
-	// "Database"): give it a signature no other file can share, so
-	// trees containing it never compare equal. Real hashes are hex, so
-	// the NUL-prefixed form cannot collide.
-	if content == "" {
-		content = "unhashed\x00" + r.path
-	}
-
 	return "f\x00" + name + "\x00" + strconv.FormatInt(r.size, 10) +
-		"\x00" + r.head + "\x00" + r.tail + "\x00" + content
+		"\x00" + string(r.head[:]) + "\x00" + string(r.tail[:]) +
+		"\x00" + string(r.content[:])
 }
 
 // collectTreeGroups groups directories by digest, counting each one on
@@ -344,7 +338,8 @@ func collectTreeGroups(allDirs []*treeNode, super *treeNode,
 // digest is the SHA-256 of its child entries — files serialized with
 // name and signature, subdirectories with name and recursive digest —
 // sorted byte-lexicographically. Filenames cannot contain NUL or "/",
-// so NUL delimiters are unambiguous.
+// and every hash and digest is 32 bytes, so NUL delimiters are
+// unambiguous.
 func (n *treeNode) computeDigest() {
 	slices.Sort(n.entries)
 

trees_test.go

@@ -10,24 +10,17 @@ import (
 	"time"
 )
 
-// Signature hashes shared by the smoke-test records.
-const (
-	f1Head    = "f1h"
-	f1Tail    = "f1t"
-	f1Content = "f1c"
-	f2Head    = "f2h"
-	f2Tail    = "f2t"
-	f2Content = "f2c"
-)
-
 // treesOpenLine is the plain line of trees' open phase when it opens
 // the database at once; it prints it as the phase starts and as it ends.
 const treesOpenLine = "[1/4] open: opening the database, elapsed 0s, " +
-	"eta unknown"
+	"remain unknown"
 
 // smokeTreeRecs mirrors the README smoke-test tree layout: /d/t1 and
 // /d/t2 are identical, /d/t3 differs from them only by one filename.
 func smokeTreeRecs() []scanRec {
+	f1Head, f1Tail, f1Content := testHash("f1h"), testHash("f1t"), testHash("f1c")
+	f2Head, f2Tail, f2Content := testHash("f2h"), testHash("f2t"), testHash("f2c")
+
 	return []scanRec{
 		{size: 3000, head: f1Head, tail: f1Tail, content: f1Content, path: "/d/t1/f1"},
 		{size: 100, head: f2Head, tail: f2Tail, content: f2Content, path: "/d/t1/sub/f2"},
@@ -153,13 +146,14 @@ func TestTreeNamesSortingBeforeSlash(t *testing.T) {
 
 	for _, top := range []string{"/a", "/c"} {
 		for _, p := range []string{"/b", "/b-x/f", "/b.txt", "/b/f"} {
-			content := "c"
+			content := testHash("c")
 			if p == "/b-x/f" {
-				content = "other"
+				content = testHash("other")
 			}
 
 			recs = append(recs, scanRec{
-				size: 1, head: "h", tail: "t", content: content, path: top + p,
+				size: 1, head: testHash("h"), tail: testHash("t"),
+				content: content, path: top + p,
 			})
 		}
 	}
@@ -242,11 +236,11 @@ func TestRunTreesProgressNamesEachPhase(t *testing.T) {
 		"trees: database " + path + " (from " + databaseEnv + ")",
 		treesOpenLine,
 		treesOpenLine,
-		"[2/4] read: counting the records, elapsed 0s, eta unknown",
+		"[2/4] read: counting the records, elapsed 0s, remain unknown",
 		"[2/4] read: [6/6] 100%, ",
-		"[3/4] group: [0/8] 0%, 0 directories/s, elapsed 0s, eta unknown",
+		"[3/4] group: [0/8] 0%, 0 directories/s, elapsed 0s, remain unknown",
 		"[3/4] group: [8/8] 100%, ",
-		"[4/4] write: [0/1] 0%, 0 groups/s, elapsed 0s, eta unknown",
+		"[4/4] write: [0/1] 0%, 0 groups/s, elapsed 0s, remain unknown",
 		"[4/4] write: [1/1] 100%, ",
 		"trees: 6 records read, 1 duplicate tree groups, 1 dupe trees, ",
 	}
@@ -279,7 +273,7 @@ func TestWriteTreeGroupsOnTerminal(t *testing.T) {
 	// No timed draws: the display is drawn as it starts and as it ends.
 	p := startProgress(progressParams{
 		label: treesPhase("write"), unit: "groups", total: int64(len(dupes)),
-	}, terminalWidth, time.Hour)
+	}, terminalWidth, time.Hour, time.Now)
 
 	_, _, err := writeTreeGroups(os.Stderr, dupes, p)
 
@@ -332,11 +326,10 @@ func TestTreeDigests(t *testing.T) {
 func TestTreeDigestContentSensitivity(t *testing.T) {
 	t.Parallel()
 
-	const sharedTail = "same"
-
+	same, c := testHash("same"), testHash("c")
 	recs := []scanRec{
-		{size: 10, head: sharedTail, tail: sharedTail, content: "c", path: "/r/a/f"},
-		{size: 10, head: "DIFF", tail: sharedTail, content: "c", path: "/r/b/f"},
+		{size: 10, head: same, tail: same, content: c, path: "/r/a/f"},
+		{size: 10, head: testHash("DIFF"), tail: same, content: c, path: "/r/b/f"},
 	}
 
 	_, dirs := treeOf(t, recs)
@@ -397,9 +390,10 @@ func TestCollectTreeGroupsSiblings(t *testing.T) {
 
 	// Identical sibling dirs share a parent, so their group cannot be
 	// implied by a parent group and must be reported.
+	h, tl, c := testHash("h"), testHash("t"), testHash("c")
 	recs := []scanRec{
-		{size: 10, head: "h", tail: "t", content: "c", path: "/p/x1/f"},
-		{size: 10, head: "h", tail: "t", content: "c", path: "/p/x2/f"},
+		{size: 10, head: h, tail: tl, content: c, path: "/p/x1/f"},
+		{size: 10, head: h, tail: tl, content: c, path: "/p/x2/f"},
 	}
 
 	super, dirs := treeOf(t, recs)
@@ -418,10 +412,11 @@ func TestCollectTreeGroupsDifferingParents(t *testing.T) {
 	// /p/a and /q/b contain identical x subtrees, but /p/a has an
 	// extra file, so the parents' digests differ and the x group must
 	// be reported.
+	h, tl, c, e := testHash("h"), testHash("t"), testHash("c"), testHash("e")
 	recs := []scanRec{
-		{size: 10, head: "h", tail: "t", content: "c", path: "/p/a/x/f"},
-		{size: 99, head: "e", tail: "e", content: "e", path: "/p/a/extra"},
-		{size: 10, head: "h", tail: "t", content: "c", path: "/q/b/x/f"},
+		{size: 10, head: h, tail: tl, content: c, path: "/p/a/x/f"},
+		{size: 99, head: e, tail: e, content: e, path: "/p/a/extra"},
+		{size: 10, head: h, tail: tl, content: c, path: "/q/b/x/f"},
 	}
 
 	super, dirs := treeOf(t, recs)