Move the command to cmd/sfdupes and the code to internal/sfdupes (closes #157)

The root held every .go file in package main, so no ref had the
path cmd/sfdupes that go install was given. cmd/sfdupes/main.go now
only calls sfdupes.Main; the rest is package internal/sfdupes, with
main.go renamed to cli.go. The Makefile builds ./cmd/sfdupes and sets
Version by its new import path. README and TODO.md give the new
install path and file paths.

The test files carry //nolint:testpackage: they test unexported
functions, which the linter allowed only in package main.

Model: opus-5-5

internal/sfdupes/cancel_test.go

@@ -0,0 +1,845 @@
+package sfdupes //nolint:testpackage // cancels the unexported runScan and hashWorker
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"slices"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"syscall"
+	"testing"
+	"time"
+)
+
+// This file gathers the tests for scan cancellation and worker-pool
+// unwinding. Everything it exercises lives in scan.go, so by the repo's
+// convention of one test file per source file it would belong in
+// scan_test.go. It is kept separate on purpose: cancellation behaviour
+// cuts across both the walk pool and the hash pool as a single concern,
+// and scan_test.go is already over 1,600 lines. That is the deliberate
+// exception the convention otherwise expects to be stated.
+
+// poolUnwind bounds how long a test waits for a cancellation to take
+// effect: for a goroutine to return or a channel to close once its
+// context is cancelled, or for a signal to cancel the scan's context.
+// Only a failing run waits this long, and the bound is what makes that
+// failure an assertion instead of a hang. A call made without it, as
+// most of this file's scans are, has no bound: a regression that parks
+// it is caught only as the test binary's own timeout.
+const poolUnwind = 2 * time.Second
+
+// walkClock is a context whose cancellation is driven by the scan's
+// own progress rather than by the wall clock: it cancels itself the
+// moment its Done method has been consulted n times. That is what
+// makes "cancel in the middle of the walk" reproducible instead of a
+// race against a timer.
+//
+// The accounting behind the n chosen by each test: every blocking
+// channel operation in the walk selects on Done, so the walk spends
+// one consultation per file event plus a couple per directory. The
+// index load that runs ahead of it also consults Done, but a bounded
+// number of times that does not grow with the record count. The tests
+// depend on that property, not on the bound's exact value: each test
+// sets n from the consultations of the walk, plus those of the hash
+// phase when it cancels mid-hash, far from both ends of the phase it
+// interrupts, so the cancellation lands inside that phase whatever the
+// record count.
+type walkClock struct {
+	n    int64
+	seen atomic.Int64
+	once sync.Once
+	done chan struct{}
+}
+
+// newWalkClock returns a context that cancels itself on the nth
+// consultation of its Done method.
+func newWalkClock(n int64) *walkClock {
+	return &walkClock{n: n, done: make(chan struct{})}
+}
+
+// Done returns the cancellation channel, cancelling the context on the
+// nth call and on every call after it. The same channel is returned
+// throughout, so a caller that took it before the cancellation still
+// observes the close.
+func (c *walkClock) Done() <-chan struct{} {
+	if c.seen.Add(1) >= c.n {
+		c.once.Do(func() { close(c.done) })
+	}
+
+	return c.done
+}
+
+// Err reports the cancellation without consuming a consultation, which
+// is what lets the post-walk guard read it without disturbing the
+// count.
+func (c *walkClock) Err() error {
+	select {
+	case <-c.done:
+		return context.Canceled
+	default:
+		return nil
+	}
+}
+
+// Deadline reports no deadline: this context is cancelled by progress,
+// never by time.
+func (c *walkClock) Deadline() (time.Time, bool) {
+	return time.Time{}, false
+}
+
+// Value carries nothing.
+func (c *walkClock) Value(_ any) any {
+	return nil
+}
+
+// walkCancelDirs and walkCancelFilesPerDir shape the fixture for the
+// mid-walk cancellation test. Spreading the files over directories is
+// load-bearing: it is what bounds how much of the tree can still be
+// walked after the cancellation, since the workers drop every
+// directory still queued and only the handful already in flight can
+// emit anything more.
+const (
+	walkCancelDirs        = 100
+	walkCancelFilesPerDir = 20
+	walkCancelFiles       = walkCancelDirs * walkCancelFilesPerDir
+	walkCancelWorkers     = 4
+	// The most files the walkCancelWorkers directories already in
+	// flight when the scan is cancelled can still emit, at
+	// walkCancelFilesPerDir each. A file count, not a directory count.
+	walkCancelInFlightFiles = walkCancelWorkers * walkCancelFilesPerDir
+)
+
+// walkCancelAtDone is the consultation on which the fixture's context
+// cancels itself. A quarter of the file count is far past the index
+// load's fixed handful and far short of the walk's total, so the
+// cancellation lands deep inside the walk and nowhere near either end
+// of it.
+const walkCancelAtDone = walkCancelFiles / 4
+
+// buildWalkCancelTree writes walkCancelFiles empty files spread over
+// walkCancelDirs subdirectories. Zero-length files are never opened by
+// the hasher, so the fixture costs directory entries and no read I/O
+// while still giving the walk thousands of events to emit.
+func buildWalkCancelTree(t *testing.T) string {
+	t.Helper()
+
+	dir := t.TempDir()
+
+	for i := range walkCancelDirs {
+		sub := filepath.Join(dir, "d"+strconv.Itoa(i))
+
+		err := os.Mkdir(sub, 0o750)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		writeEmptyFiles(t, sub, walkCancelFilesPerDir)
+	}
+
+	return dir
+}
+
+// assertRecordsIntact fails when the database no longer holds exactly
+// the records it held before, reporting the first difference rather
+// than dumping thousands of paths.
+func assertRecordsIntact(t *testing.T, db *sql.DB, before []string) {
+	t.Helper()
+
+	got := recordPaths(dbRecords(t, db))
+	if len(got) != len(before) {
+		t.Fatalf("%d records after the cancelled scan, want %d",
+			len(got), len(before))
+	}
+
+	for i := range got {
+		if got[i] != before[i] {
+			t.Fatalf("record %d = %q after the cancelled scan, want %q",
+				i, got[i], before[i])
+		}
+	}
+}
+
+// TestSyncScanCancelledMidWalkKeepsRecords is the regression net under
+// the post-walk guard. The scan is cancelled part-way through the
+// 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
+// unreachable, makes the scan carry its truncated view into the update
+// phase, which counts every record the walk never reached for removal.
+//
+// The syncScan call here is not bounded by poolUnwind: a regression
+// that left a worker pool parked would hang it, and that regression is
+// caught only by the test binary's own timeout, not by a quick
+// assertion.
+//
+//nolint:paralleltest // counts goroutines: must not run beside others
+func TestSyncScanCancelledMidWalkKeepsRecords(t *testing.T) {
+	dir := buildWalkCancelTree(t)
+	db := openTestDB(t)
+
+	st := syncTree(t, db, dir)
+	if st.added != walkCancelFiles {
+		t.Fatalf("setup scan added %d records, want %d",
+			st.added, walkCancelFiles)
+	}
+
+	before := recordPaths(dbRecords(t, db))
+	base := baselineGoroutines(t)
+
+	st, err := syncScan(newWalkClock(walkCancelAtDone), db,
+		[]string{dir}, walkCancelWorkers, false, walkRules{})
+
+	assertWalkGuardAborted(t, st, err)
+	assertRecordsIntact(t, db, before)
+
+	if got := settledGoroutines(t, base); got > base {
+		t.Errorf("goroutines = %d after the cancelled scan, want %d back",
+			got, base)
+	}
+}
+
+// assertWalkGuardAborted checks that the scan stopped at the post-walk
+// 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()
+
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("syncScan cancelled mid-walk = %v, want %v",
+			err, context.Canceled)
+	}
+
+	if st.unchanged == 0 {
+		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 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 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("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 walk", st)
+	}
+}
+
+// TestSyncScanCancelledBeforeLoadIndex covers the trivial end of the
+// cancellation path: a scan handed a context that is already cancelled
+// fails in the index load, before the walk pool is ever started. It
+// says nothing about the post-walk guard — nothing downstream of
+// loadIndex runs at all — only that the failure surfaces as a
+// cancellation and that no record is touched on the way out.
+func TestSyncScanCancelledBeforeLoadIndex(t *testing.T) {
+	t.Parallel()
+
+	dir := buildSmokeTree(t)
+	db := openTestDB(t)
+
+	syncTree(t, db, dir)
+
+	before := recordPaths(dbRecords(t, db))
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	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)
+	}
+
+	if st != (scanStats{}) {
+		t.Errorf("stats = %+v, want none: the scan gave up in the index "+
+			"load, before any phase ran", st)
+	}
+
+	assertRecordsIntact(t, db, before)
+}
+
+// hashCancelAtDone is the consultation on which the mid-hash test's
+// context cancels itself. The walk of buildWalkCancelTree spends about
+// one per file and three per directory, and the hash phase then one per
+// file hashed, so this lands about half way through the hash phase.
+const hashCancelAtDone = walkCancelFiles + 3*walkCancelDirs +
+	walkCancelFiles/2
+
+// TestSyncScanCancelledMidHashKeepsHashedRecords cancels a first scan
+// part-way through its hash phase. The fixture holds fewer files than a
+// batch, so every file hashed is still waiting to be committed: the scan
+// must commit them all before it returns, and the next scan must hash
+// only the rest.
+func TestSyncScanCancelledMidHashKeepsHashedRecords(t *testing.T) {
+	t.Parallel()
+
+	dir := buildWalkCancelTree(t)
+	db := openTestDB(t)
+
+	st, err := syncScan(newWalkClock(hashCancelAtDone), db,
+		[]string{dir}, walkCancelWorkers, false, walkRules{})
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("syncScan cancelled mid-hash = %v, want %v",
+			err, context.Canceled)
+	}
+
+	if st.walked != walkCancelFiles || st.added == 0 ||
+		st.added >= walkCancelFiles {
+		t.Fatalf("stats = %+v: want the walk complete and the hash phase "+
+			"cut short", st)
+	}
+
+	if got := len(dbRecords(t, db)); got != st.added {
+		t.Errorf("%d records after the cancelled scan, want the %d it hashed",
+			got, st.added)
+	}
+
+	hashed := st.added
+
+	st = syncTree(t, db, dir)
+	if st.added != walkCancelFiles-hashed || st.unchanged != hashed {
+		t.Errorf("next scan stats = %+v, want %d added %d unchanged",
+			st, walkCancelFiles-hashed, hashed)
+	}
+}
+
+// storedPaths opens the database at path as report does, which fails
+// unless it is a valid database, and returns its records' paths.
+func storedPaths(t *testing.T, path string) []string {
+	t.Helper()
+
+	db, err := openReportDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	return recordPaths(dbRecords(t, db))
+}
+
+// TestRunScanInterrupted calls the scan entrypoint with a context that
+// is already cancelled, as when a signal arrives at once. It must return
+// errInterrupted promptly, with its line on stderr after the one naming
+// the database and nothing on stdout, leave the database valid and as
+// it was, and leave nothing in the way of the next scan, which must
+// bring the database up to date.
+func TestRunScanInterrupted(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	stdout := captureStdout(t)
+	stderr := captureStderr(t)
+	dir := buildSmokeTree(t)
+
+	err := runScan(t.Context(), []string{dir}, walkCancelWorkers, false,
+		false)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	before := storedPaths(t, path)
+
+	// A vanished file and a new one: the interrupted scan records
+	// neither.
+	gone := filepath.Join(dir, "a", "unique.bin")
+
+	err = os.Remove(gone)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	added := writeFile(t, dir, "a/new.bin", pattern(50, 10))
+	shown := len(stderr())
+	done := make(chan struct{})
+
+	go func() {
+		defer close(done)
+
+		err = runScan(cancelledContext(t), []string{dir}, walkCancelWorkers,
+			false, false)
+	}()
+
+	awaitReturn(t, done, "runScan")
+
+	if !errors.Is(err, errInterrupted) {
+		t.Fatalf("runScan on a cancelled context = %v, want %v",
+			err, errInterrupted)
+	}
+
+	want := "scan: database " + path + " (from " + databaseEnv + ")\n" +
+		"scan: interrupted after 0 files\n"
+	if got := stderr()[shown:]; got != want {
+		t.Errorf("stderr = %q, want %q", got, want)
+	}
+
+	if got := stdout(); got != "" {
+		t.Errorf("stdout = %q, want nothing (data only)", got)
+	}
+
+	assertNoSidecars(t, path)
+
+	if got := storedPaths(t, path); !slices.Equal(got, before) {
+		t.Errorf("records = %q after the interrupted scan, want %q",
+			got, before)
+	}
+
+	err = runScan(t.Context(), []string{dir}, walkCancelWorkers, false,
+		false)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got := storedPaths(t, path)
+	if slices.Contains(got, gone) || !slices.Contains(got, added) {
+		t.Errorf("records = %q after the next scan, want %q gone and %q "+
+			"added", got, gone, added)
+	}
+}
+
+// TestRunScanInterruptedMidHash interrupts the scan entrypoint part-way
+// through its hash phase, after the database is open. It must return
+// errInterrupted, release the lock, end stderr with its line counting
+// every file the walk reached, write nothing to stdout, close the
+// database out of WAL mode, and keep the records it hashed.
+func TestRunScanInterruptedMidHash(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	stdout := captureStdout(t)
+	stderr := captureStderr(t)
+	dir := buildWalkCancelTree(t)
+
+	err := runScan(newWalkClock(hashCancelAtDone), []string{dir},
+		walkCancelWorkers, false, false)
+	if !errors.Is(err, errInterrupted) {
+		t.Fatalf("runScan interrupted mid-hash = %v, want %v",
+			err, errInterrupted)
+	}
+
+	holdScanLock(t, path)
+
+	want := fmt.Sprintf("scan: interrupted after %d files\n", walkCancelFiles)
+	if got := stderr(); !strings.HasSuffix(got, want) {
+		t.Errorf("stderr = %q, want it to end with %q", got, want)
+	}
+
+	if got := stdout(); got != "" {
+		t.Errorf("stdout = %q, want nothing (data only)", got)
+	}
+
+	assertNoSidecars(t, path)
+
+	db, err := openReportDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	// A plain close also removes the sidecars, but leaves WAL mode on.
+	var mode string
+
+	err = db.QueryRowContext(t.Context(), "PRAGMA journal_mode").Scan(&mode)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if mode != "delete" {
+		t.Errorf("journal mode = %q after the interrupted scan, want %q",
+			mode, "delete")
+	}
+
+	kept := len(dbRecords(t, db))
+	if kept == 0 || kept >= walkCancelFiles {
+		t.Errorf("%d records after the interrupted scan, want those it "+
+			"hashed: some but not all of the %d files", kept, walkCancelFiles)
+	}
+}
+
+// TestInterruptContextCatchesSIGTERM sends SIGTERM to the test process
+// while the scan's handler is installed, and checks that it cancels the
+// scan's context.
+//
+//nolint:paralleltest // signals the whole process: must not run beside a scan
+func TestInterruptContextCatchesSIGTERM(t *testing.T) {
+	// Caught here as well, so that a handler that misses SIGTERM fails
+	// this test instead of ending the test process.
+	caught := make(chan os.Signal, 1)
+	signal.Notify(caught, syscall.SIGTERM)
+
+	defer signal.Stop(caught)
+
+	ctx, stop := interruptContext(t.Context())
+	defer stop()
+
+	err := syscall.Kill(os.Getpid(), syscall.SIGTERM)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	select {
+	case <-ctx.Done():
+	case <-time.After(poolUnwind):
+		t.Fatal("SIGTERM did not cancel the scan's context")
+	}
+}
+
+// TestCommitFullBatchKeepsFailedBatch checks that a full batch whose
+// commit fails, as it does once the scan is interrupted, stays in the
+// batch, so that syncScan's final commit saves it.
+func TestCommitFullBatchKeepsFailedBatch(t *testing.T) {
+	t.Parallel()
+
+	s := &scanState{db: openTestDB(t)}
+	for i := range updateBatchSize {
+		s.batch = append(s.batch, scanRec{path: "/f" + strconv.Itoa(i)})
+	}
+
+	err := s.commitFullBatch(cancelledContext(t))
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("commitFullBatch on a cancelled context = %v, want %v",
+			err, context.Canceled)
+	}
+
+	if len(s.batch) != updateBatchSize {
+		t.Errorf("batch holds %d records after the failed commit, want %d",
+			len(s.batch), updateBatchSize)
+	}
+}
+
+// drainClosed counts the values received from ch until it closes,
+// failing the test if it does not close within poolUnwind. A pool that
+// ignored its cancellation leaves its channel open with its goroutines
+// parked, and this is what reports that as an assertion.
+func drainClosed[T any](t *testing.T, ch <-chan T, what string) int {
+	t.Helper()
+
+	counted := make(chan int, 1)
+
+	go func() {
+		n := 0
+		for range ch {
+			n++
+		}
+
+		counted <- n
+	}()
+
+	select {
+	case n := <-counted:
+		return n
+	case <-time.After(poolUnwind):
+		t.Fatalf("%s stayed open after cancellation", what)
+
+		return 0
+	}
+}
+
+// awaitReturn fails the test if done is not closed within poolUnwind.
+func awaitReturn(t *testing.T, done <-chan struct{}, what string) {
+	t.Helper()
+
+	select {
+	case <-done:
+	case <-time.After(poolUnwind):
+		t.Fatalf("%s did not return after cancellation", what)
+	}
+}
+
+// cancelledContext returns a context that is already cancelled.
+func cancelledContext(t *testing.T) context.Context {
+	t.Helper()
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	return ctx
+}
+
+// TestSendEventAbandonsBlockedSend checks that a walk goroutine with an
+// event to deliver and nobody to deliver it to leaves on cancellation
+// instead of holding the pool open. The channel here is unbuffered and
+// unread, so the send can never complete.
+func TestSendEventAbandonsBlockedSend(t *testing.T) {
+	t.Parallel()
+
+	done := make(chan struct{})
+	events := make(chan walkEvent)
+
+	go func() {
+		defer close(done)
+
+		sendEvent(cancelledContext(t), events, walkEvent{})
+	}()
+
+	awaitReturn(t, done, "sendEvent")
+}
+
+// TestWalkOneDirStopsWhenCancelled checks that a cancelled scan stops
+// reading a directory instead of going through the rest of its
+// entries. A walk that kept going would return the subdirectory below
+// to descend into. Unlike a file event, that return is not a send the
+// cancellation can abandon, so the test catches the regression every
+// time.
+func TestWalkOneDirStopsWhenCancelled(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+
+	err := os.Mkdir(filepath.Join(dir, "sub"), 0o750)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Unbuffered and unread: on a cancelled scan every send gives up.
+	events := make(chan walkEvent)
+
+	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)
+	}
+}
+
+// TestWalkWorkersDropQueuedDirs checks that cancelled walk workers keep
+// reading jobs and drop the directories rather than stopping their
+// read: the range over jobs has to run out for the pool to tear down
+// and close its event stream. The queued directory does not exist, so
+// a worker that walked it anyway would send a warning before
+// walkOneDir's own cancellation check could stop it. On a cancelled
+// scan that send delivers or gives up at random, so with 64 jobs
+// queued the regression has a one in 2^64 chance of passing.
+func TestWalkWorkersDropQueuedDirs(t *testing.T) {
+	t.Parallel()
+
+	missing := filepath.Join(t.TempDir(), "missing")
+
+	jobs, _, events := startWalkWorkers(cancelledContext(t), 2, false,
+		walkRules{})
+
+	for range 64 {
+		jobs <- dirJob{path: missing}
+	}
+
+	close(jobs)
+
+	if n := drainClosed(t, events, "the walk event stream"); n != 0 {
+		t.Errorf("cancelled walk workers emitted %d events, want none", n)
+	}
+}
+
+// TestWalkWorkerAbandonsSubdirHandoff checks the other blocking send a
+// walk worker makes: handing discovered subdirectories back to the
+// dispatcher. Once the dispatcher has left, nothing drains that
+// channel, and a worker parked on it would hold the pool open forever.
+func TestWalkWorkerAbandonsSubdirHandoff(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	writeEmptyFiles(t, dir, 1)
+
+	err := os.Mkdir(filepath.Join(dir, "sub"), 0o750)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	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.
+	subdirs <- nil
+
+	jobs <- dirJob{path: dir}
+
+	// The file event proves the worker has read the directory and has
+	// nothing left to do but the blocked hand-back.
+	ev := <-events
+	if ev.fail {
+		t.Fatalf("walk event = %+v, want the fixture file", ev)
+	}
+
+	cancel()
+	close(jobs)
+	drainClosed(t, events, "the walk event stream")
+}
+
+// TestDispatchDirsClosesJobsWhenCancelled checks that a dispatcher
+// leaving on cancellation closes the job channel on its way out. The
+// workers range over that channel; a dispatcher that returned without
+// closing it would strand every one of them.
+func TestDispatchDirsClosesJobsWhenCancelled(t *testing.T) {
+	t.Parallel()
+
+	// Unbuffered and unread: with no worker pool behind it, the
+	// dispatcher can only leave through its cancellation case.
+	jobs := make(chan dirJob)
+	subdirs := make(chan []dirJob)
+	initial := []dirJob{{path: "/a"}, {path: "/b"}}
+
+	dispatchDirs(cancelledContext(t), initial, jobs, subdirs)
+
+	if n := drainClosed(t, jobs, "the walk job queue"); n > len(initial) {
+		t.Errorf("dispatcher queued %d jobs, want at most %d",
+			n, len(initial))
+	}
+}
+
+// TestFeedHashJobsClosesJobsWhenCancelled checks that the hash feeder
+// abandons the runs it has not queued yet and still closes the job
+// channel, which is what lets the workers' range terminate. The
+// receive on jobs below is not bounded: a feeder that returned without
+// closing jobs would leave that receive with no sender and no close, so
+// this regression is caught by the test binary's timeout rather than by
+// a bounded assertion.
+func TestFeedHashJobsClosesJobsWhenCancelled(t *testing.T) {
+	t.Parallel()
+
+	done := make(chan struct{})
+	// Unbuffered and unread until the feeder has returned, so the only
+	// way out of the feeder is its cancellation case.
+	jobs := make(chan []fileRec)
+	runs := [][]fileRec{{{path: "a"}}, {{path: "b"}}}
+
+	go func() {
+		defer close(done)
+
+		feedHashJobs(cancelledContext(t), runs, jobs)
+	}()
+
+	awaitReturn(t, done, "feedHashJobs")
+
+	if _, ok := <-jobs; ok {
+		t.Error("the hash job channel was left open after cancellation")
+	}
+}
+
+// TestHashWorkerDropsQueuedRuns checks that a cancelled hash worker
+// keeps reading jobs and drops the runs rather than reading files
+// nobody wants the hashes of — while still letting the range run out
+// so the pool tears down. The hash function records that it was
+// called, so a worker that hashed the queued run anyway is caught
+// every time.
+func TestHashWorkerDropsQueuedRuns(t *testing.T) {
+	t.Parallel()
+
+	done := make(chan struct{})
+	jobs := make(chan []fileRec, 1)
+	results := make(chan hashResult)
+
+	jobs <- []fileRec{{path: filepath.Join(t.TempDir(), "missing"), size: 1}}
+
+	close(jobs)
+
+	var hashed atomic.Bool
+
+	hash := func(path string, size int64) (
+		[sha256.Size]byte, [sha256.Size]byte, [sha256.Size]byte, error,
+	) {
+		hashed.Store(true)
+
+		return hashSignature(path, size)
+	}
+
+	go func() {
+		defer close(done)
+
+		hashWorker(cancelledContext(t), jobs, results, hash)
+	}()
+
+	awaitReturn(t, done, "hashWorker")
+
+	if hashed.Load() {
+		t.Error("cancelled hash worker hashed the queued run, want it dropped")
+	}
+}
+
+// TestHashWorkerAbandonsBlockedSend checks that a hash worker with a
+// result to deliver and nobody to deliver it to leaves once the scan
+// is cancelled, instead of holding the pool open. The scan tests do
+// not catch this: stop drains results, which frees a parked worker
+// anyway.
+func TestHashWorkerAbandonsBlockedSend(t *testing.T) {
+	t.Parallel()
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	done := make(chan struct{})
+	jobs := make(chan []fileRec, 1)
+	// Unbuffered and unread, with jobs left open: the worker's only way
+	// out is the cancellation case beside its send.
+	results := make(chan hashResult)
+
+	jobs <- []fileRec{{path: filepath.Join(t.TempDir(), "missing"), size: 1}}
+
+	// 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) (
+		[sha256.Size]byte, [sha256.Size]byte, [sha256.Size]byte, error,
+	) {
+		cancel()
+
+		return hashSignature(path, size)
+	}
+
+	go func() {
+		defer close(done)
+
+		hashWorker(ctx, jobs, results, hash)
+	}()
+
+	awaitReturn(t, done, "hashWorker")
+}
+
+// TestHashPhaseCancelledReturnsContextError checks the result loop's
+// own exit: with the pool cancelled, no result will ever arrive, and
+// the loop must leave through the cancellation rather than wait for a
+// receive that cannot happen. This call is not bounded by poolUnwind: a
+// loop that dropped its cancellation case would block on that receive,
+// so the regression surfaces as the test binary's timeout rather than
+// as a bounded assertion.
+func TestHashPhaseCancelledReturnsContextError(t *testing.T) {
+	t.Parallel()
+
+	s := &scanState{
+		db:     openTestDB(t),
+		toHash: []fileRec{{path: "a", size: 1, dev: 1, ino: 1}},
+	}
+
+	err := s.hashPhase(cancelledContext(t), 2)
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("hashPhase on a cancelled context = %v, want %v",
+			err, context.Canceled)
+	}
+}

internal/sfdupes/cli.go

@@ -0,0 +1,289 @@
+// Package sfdupes implements the sfdupes command and the database its
+// subcommands share.
+package sfdupes
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"runtime"
+	"runtime/debug"
+
+	"github.com/spf13/cobra"
+)
+
+// Exit codes: exitOK is success (even with per-file warnings),
+// exitFatal is a fatal error, exitUsage is a usage error.
+const (
+	exitOK    = 0
+	exitFatal = 1
+	exitUsage = 2
+)
+
+// The subcommand names, as typed on the command line.
+const (
+	cmdScan   = "scan"
+	cmdReport = "report"
+	cmdTrees  = "trees"
+	cmdInfo   = "info"
+	cmdDwim   = "dwim"
+)
+
+// errNoSubcommand is returned by the root command when it is invoked
+// without a subcommand. That is a usage error, and the usage text
+// cobra prints for it is the whole message.
+var errNoSubcommand = errors.New("no subcommand")
+
+// errWorkersBelowOne is the usage error for a scan --workers value
+// below 1.
+var errWorkersBelowOne = errors.New("--workers must be at least 1")
+
+// Version is the build version, injected at link time via -ldflags
+// (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 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
+}
+
+// Main runs the command line in os.Args and returns the process exit
+// code.
+func Main() int {
+	// Once the reader of a stdout pipe has gone, as in "sfdupes report |
+	// head", the Go runtime ends the process with SIGPIPE on the next
+	// write instead of returning an error (README "Error handling").
+	// Registering for SIGPIPE with os/signal would change that.
+	return run(os.Args[1:], os.Stdout, os.Stderr)
+}
+
+// run executes args against the command tree and returns the process
+// exit code. It is the program's single exit point: the subcommands
+// return their errors instead of exiting, so every deferred cleanup —
+// above all closing the database, which checkpoints the SQLite WAL —
+// runs before the process ends. The report, trees, info and dwim
+// subcommands write their data to stdout.
+func run(args []string, stdout, stderr io.Writer) int {
+	// A nil slice makes cobra fall back to os.Args, which would let a
+	// test binary's own flags reach the command tree.
+	if args == nil {
+		args = []string{}
+	}
+
+	root := newRootCommand(stdout, stderr)
+	root.SetArgs(args)
+
+	err := root.Execute()
+
+	var fatal fatalError
+
+	switch {
+	case err == nil:
+		return exitOK
+	case errors.Is(err, errInterrupted):
+		// The interrupted scan has printed its own line.
+		return exitFatal
+	case errors.As(err, &fatal):
+		// The command ran and failed: a runtime error, reported
+		// without the usage text that a usage error gets.
+		_, _ = fmt.Fprintf(stderr, "sfdupes: %v\n", err)
+
+		return exitFatal
+	default:
+		// A usage error, which cobra has already reported on stderr.
+		return exitUsage
+	}
+}
+
+// newRootCommand builds the command tree. Everything on stdout is
+// machine-readable data, the version line included; all human-facing
+// output (help, usage, errors) goes to stderr.
+func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
+	var showVersion bool
+
+	printVersion := runE(func(context.Context, []string) error {
+		info, _ := debug.ReadBuildInfo()
+
+		_, err := fmt.Fprintf(stdout, "sfdupes %s\n",
+			buildVersion(Version, info))
+		if err != nil {
+			return fmt.Errorf("write stdout: %w", err)
+		}
+
+		return nil
+	})
+
+	root := &cobra.Command{
+		Use:   "sfdupes",
+		Short: "Find candidate duplicate files by size and head/tail/content SHA-256",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if showVersion {
+				return printVersion(cmd, args)
+			}
+
+			// A missing subcommand prints usage and exits 2: cobra
+			// prints the usage text for the returned error, and run
+			// maps everything that is not a fatal error to exit 2.
+			cmd.SilenceErrors = true
+
+			return errNoSubcommand
+		},
+	}
+	root.SetOut(stderr)
+	root.SetErr(stderr)
+	root.CompletionOptions.DisableDefaultCmd = true
+
+	// Cobra's built-in version flag prints through the help writer,
+	// stderr; this one prints to stdout.
+	root.Flags().BoolVarP(&showVersion, "version", "v", false,
+		"print the version to stdout")
+
+	reportCmd := &cobra.Command{
+		Use:   cmdReport,
+		Short: "Read the scan database and print the file-level duplicates report",
+		Args:  cobra.NoArgs,
+		RunE: runE(func(ctx context.Context, _ []string) error {
+			return runReport(ctx, stdout)
+		}),
+	}
+
+	treesCmd := &cobra.Command{
+		Use:   cmdTrees,
+		Short: "Read the scan database and print the duplicate-tree report",
+		Args:  cobra.NoArgs,
+		RunE: runE(func(ctx context.Context, _ []string) error {
+			return runTrees(ctx, stdout)
+		}),
+	}
+
+	infoCmd := &cobra.Command{
+		Use:   cmdInfo,
+		Short: "Read the scan database and print its details",
+		Args:  cobra.NoArgs,
+		RunE: runE(func(ctx context.Context, _ []string) error {
+			return runInfo(ctx, stdout)
+		}),
+	}
+
+	dwimCmd := &cobra.Command{
+		Use:   cmdDwim,
+		Short: "Scan / with the default excludes, then print the duplicate-tree report",
+		Args:  cobra.NoArgs,
+		RunE: runE(func(ctx context.Context, _ []string) error {
+			return runDwim(ctx, "/", stdout)
+		}),
+	}
+
+	root.AddCommand(newScanCommand(), reportCmd, treesCmd, infoCmd, dwimCmd)
+
+	return root
+}
+
+// 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
+		scanNoDefaultExcludes bool
+	)
+
+	short := "Walk trees and synchronize the scan database"
+
+	scanCmd := &cobra.Command{
+		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)
+		},
+		RunE: runE(func(ctx context.Context, args []string) error {
+			ctx, stop := interruptContext(ctx)
+			defer stop()
+
+			return runScan(ctx, args, scanWorkers, scanOneFS,
+				scanNoDefaultExcludes)
+		}),
+	}
+	scanCmd.Flags().IntVar(&scanWorkers, "workers", runtime.NumCPU(),
+		"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
+}
+
+// checkScanWorkers rejects a scan --workers value below 1. That is a
+// usage error reported in one line: cobra prints the returned message
+// without the usage text, and run exits 2.
+func checkScanWorkers(cmd *cobra.Command, workers int) error {
+	if workers >= 1 {
+		return nil
+	}
+
+	cmd.SilenceUsage = true
+
+	return fmt.Errorf("%w, got %d", errWorkersBelowOne, workers)
+}
+
+// runE adapts a subcommand implementation, or the version print, to
+// cobra's RunE. Cobra prints the error and the command's usage text for
+// every error RunE returns, but a subcommand that ran and failed has no
+// usage problem to report: both are silenced here, and the error is
+// marked fatal so that run reports it on stderr and exits 1 rather than
+// 2. The command's context is handed to the implementation: cancelling
+// it unwinds the scan's worker pools.
+func runE(
+	fn func(ctx context.Context, args []string) error,
+) func(*cobra.Command, []string) error {
+	return func(cmd *cobra.Command, args []string) error {
+		cmd.SilenceUsage = true
+		cmd.SilenceErrors = true
+
+		err := fn(cmd.Context(), args)
+		if err != nil {
+			return fatalError{err: err}
+		}
+
+		return nil
+	}
+}
+
+// fatalError marks a runtime failure, as opposed to the usage errors
+// cobra itself produces while parsing arguments and flags. Both come
+// out of Execute as plain errors, so the wrapper is what tells run to
+// report this one as "sfdupes: ..." and exit 1.
+type fatalError struct {
+	err error
+}
+
+func (e fatalError) Error() string { return e.err.Error() }
+
+func (e fatalError) Unwrap() error { return e.err }

internal/sfdupes/db.go

@@ -0,0 +1,935 @@
+package sfdupes
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"errors"
+	"fmt"
+	"io/fs"
+	"net/url"
+	"os"
+	"path/filepath"
+	"slices"
+	"strconv"
+	"strings"
+	"time"
+
+	"golang.org/x/sys/unix"
+	// The pure-Go SQLite driver, registered as "sqlite"; keeps cgo
+	// disabled.
+	_ "modernc.org/sqlite"
+)
+
+// defaultDatabasePath is where the persistent scan database lives when
+// SFDUPES_DATABASE is not set.
+const defaultDatabasePath = "/var/lib/sfdupes/db.sqlite"
+
+// databaseEnv is the environment variable that overrides the database
+// path.
+const databaseEnv = "SFDUPES_DATABASE"
+
+// schemaVersion is the database schema version this build reads and
+// writes, stored in PRAGMA user_version.
+const schemaVersion = 1
+
+// dbDirPerm is the mode for a database parent directory created by
+// scan.
+const dbDirPerm = 0o755
+
+// dbFilePerm is the mode for a database file created by scan, the mode
+// SQLite gives a database file it creates.
+const dbFilePerm = 0o644
+
+// lockFilePerm is the mode for the scan lock file. Anyone who can open
+// the file can hold the lock and keep every scan from running, so it
+// is open to its owner only.
+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.
+// disk_size holds the bytes the file takes on disk. mtime holds whole
+// Unix seconds and mtime_nsec the nanoseconds within that 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,
+    disk_size  INTEGER NOT NULL,
+    mtime      INTEGER NOT NULL,
+    mtime_nsec INTEGER NOT NULL,
+    head       BLOB NOT NULL,
+    tail       BLOB NOT NULL,
+    content    BLOB NOT NULL
+) WITHOUT ROWID
+`
+
+// createIndexSQL indexes the records by signature, so report can read
+// them in signature order without sorting the table.
+const createIndexSQL = `
+CREATE INDEX files_signature ON files (size, head, tail, content)
+`
+
+// createTotalsSQL creates the totals table, which holds one row: the
+// number of records and the sizes of all records added up. Counting
+// them over files would read every record. The three triggers below
+// keep the row current, in the transaction of each change to files.
+const createTotalsSQL = `
+CREATE TABLE totals (
+    records INTEGER NOT NULL,
+    size    INTEGER NOT NULL
+)
+`
+
+// insertTotalsSQL adds the one row of totals, for an empty files table.
+const insertTotalsSQL = `
+INSERT INTO totals (records, size) VALUES (0, 0)
+`
+
+// totalsAfterInsertSQL counts each inserted record into totals.
+const totalsAfterInsertSQL = `
+CREATE TRIGGER totals_after_insert AFTER INSERT ON files BEGIN
+    UPDATE totals SET records = records + 1, size = size + NEW.size;
+END
+`
+
+// totalsAfterDeleteSQL takes each deleted record out of totals.
+const totalsAfterDeleteSQL = `
+CREATE TRIGGER totals_after_delete AFTER DELETE ON files BEGIN
+    UPDATE totals SET records = records - 1, size = size - OLD.size;
+END
+`
+
+// totalsAfterUpdateSQL replaces a record's old size in totals with its
+// new one. scan's upsert of an existing record is such an update.
+const totalsAfterUpdateSQL = `
+CREATE TRIGGER totals_after_update AFTER UPDATE OF size ON files BEGIN
+    UPDATE totals SET size = size + NEW.size - OLD.size;
+END
+`
+
+// recordCountSQL reads the number of records from totals.
+const recordCountSQL = `
+SELECT records FROM totals
+`
+
+// upsertSQL inserts one file record, replacing any existing record for
+// the same path.
+const upsertSQL = `
+INSERT INTO files (
+    path, size, disk_size, mtime, mtime_nsec, head, tail, content
+)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT (path) DO UPDATE SET
+    size = excluded.size, disk_size = excluded.disk_size,
+    mtime = excluded.mtime, mtime_nsec = excluded.mtime_nsec,
+    head = excluded.head, tail = excluded.tail,
+    content = excluded.content
+`
+
+// errNoDatabase reports a missing database file for report, trees and
+// info.
+var errNoDatabase = errors.New(
+	"no database (run \"sfdupes scan\" first, or set " + databaseEnv + ")")
+
+// errSchemaVersion reports a database whose schema version this build
+// does not understand.
+var errSchemaVersion = errors.New("unsupported database schema version")
+
+// errScanRunning reports that another scan holds the lock on the
+// 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, made absolute by absolutePath, and where the path came from,
+// "default" or "from SFDUPES_DATABASE", for the line each subcommand
+// prints first on stderr.
+func databasePath() (string, string, error) {
+	path, source := defaultDatabasePath, "default"
+	if p := os.Getenv(databaseEnv); p != "" {
+		path, source = p, "from "+databaseEnv
+	}
+
+	abs, err := absolutePath(path)
+	if err != nil {
+		return "", "", fmt.Errorf("resolve database path %s: %w", path, err)
+	}
+
+	return abs, source, nil
+}
+
+// absolutePath returns path unchanged when it is absolute, and
+// otherwise the working directory, a "/" and path. The working
+// directory is the one the kernel reports, with no symlink in it;
+// os.Getwd may return PWD instead, which can name it through a symlink.
+// The result is not cleaned, as filepath.Abs and filepath.Join would
+// clean it. Cleaning drops each ".." together with the directory name
+// before it. When that name is a symlink, the cleaned path names
+// another file than the one the system reaches by following the symlink
+// first.
+func absolutePath(path string) (string, error) {
+	if filepath.IsAbs(path) {
+		return path, nil
+	}
+
+	wd, err := unix.Getwd()
+	if err != nil {
+		return "", err
+	}
+
+	// The working directory ends in "/" only when it is the root.
+	return strings.TrimSuffix(wd, "/") + "/" + path, 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.
+//
+// Each write to files fires a trigger, so SQLite keeps a statement
+// journal for it. temp_store(MEMORY) keeps that journal in memory,
+// which costs far less than a temporary file.
+const scanParams = "_pragma=busy_timeout(10000)" +
+	"&_pragma=journal_mode(WAL)" +
+	"&_pragma=synchronous(NORMAL)" +
+	"&_pragma=temp_store(MEMORY)"
+
+// reportParams are the connection parameters for report, trees and
+// info: read-only, with the same busy timeout. They set no journal
+// mode, because setting one is a write.
+const reportParams = "mode=ro" +
+	"&_pragma=busy_timeout(10000)" +
+	"&_pragma=query_only(1)"
+
+// openDB opens the SQLite database at path with the connection
+// parameters params. It does not create or verify the schema.
+func openDB(path, params string) (*sql.DB, error) {
+	// The path is escaped into a file: URI, so ?, # and % in it stay
+	// part of the file name. SQLite reads what follows file:// up to
+	// the next / as a host name, so an absolute path goes after an
+	// empty host (file:///abs) and a relative path goes without one
+	// (file:rel).
+	uri := url.URL{
+		Scheme:   "file",
+		OmitHost: !filepath.IsAbs(path),
+		Path:     path,
+		RawQuery: params,
+	}
+
+	db, err := sql.Open("sqlite", uri.String())
+	if err != nil {
+		return nil, fmt.Errorf("open database %s: %w", path, err)
+	}
+
+	// A single connection avoids SQLITE_BUSY between this process's
+	// own connections; concurrency lives in the worker pools, not in
+	// parallel database access.
+	db.SetMaxOpenConns(1)
+
+	return db, nil
+}
+
+// lockScanDatabase takes the lock that keeps a second scan off the
+// database at path: an exclusive flock(2) on the file beside it named
+// by the database's path with symlinks resolved and ".lock" appended,
+// so every path to one database names the same lock file. If missing,
+// the database's parent directory and an empty database file are
+// created first, so the lock file is named the same way before the
+// database is set up as after. A lock held by another scan fails at
+// once instead of waiting. The lock lasts until the returned file is
+// closed or the process ends. The lock file is never deleted: a scan
+// 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 := createDatabaseDirectory(path)
+	if err != nil {
+		return nil, err
+	}
+
+	// Like SQLite, this follows a symlink at path and creates its
+	// target. SQLite opens an empty file as a new database.
+	//nolint:gosec // the operator chooses the database path
+	dbFile, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE, dbFilePerm)
+	if err != nil {
+		return nil, fmt.Errorf("create database: %w", err)
+	}
+
+	_ = dbFile.Close()
+
+	resolved, err := filepath.EvalSymlinks(path)
+	if err != nil {
+		return nil, fmt.Errorf("resolve database path: %w", err)
+	}
+
+	lockPath := resolved + ".lock"
+
+	//nolint:gosec // the operator chooses the database path
+	f, err := os.OpenFile(lockPath, os.O_RDWR|os.O_CREATE, lockFilePerm)
+	if err != nil {
+		return nil, err
+	}
+
+	err = unix.Flock(int(f.Fd()), unix.LOCK_EX|unix.LOCK_NB)
+	if err != nil {
+		_ = f.Close()
+
+		if errors.Is(err, unix.EWOULDBLOCK) {
+			return nil, fmt.Errorf("%w (lock held on %s)",
+				errScanRunning, lockPath)
+		}
+
+		return nil, fmt.Errorf("lock %s: %w", lockPath, err)
+	}
+
+	return f, nil
+}
+
+// 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 := createDatabaseDirectory(path)
+	if err != nil {
+		return nil, err
+	}
+
+	db, err := openDB(path, scanParams)
+	if err != nil {
+		return nil, err
+	}
+
+	err = initSchema(ctx, db)
+	if err != nil {
+		_ = db.Close()
+
+		return nil, fmt.Errorf("database %s: %w", path, err)
+	}
+
+	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
+// -shm file beside it, nor write access to create them. The switch
+// fails while a report has the database open; the database then stays
+// in WAL mode, still readable, until a later scan closes it.
+func closeScanDatabase(ctx context.Context, db *sql.DB, path string) {
+	// Runs on the way out of a cancelled scan too.
+	_, err := db.ExecContext(context.WithoutCancel(ctx),
+		"PRAGMA journal_mode = DELETE")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "scan: database %s left in WAL mode: %v\n",
+			path, err)
+	}
+
+	_ = db.Close()
+}
+
+// openReportDatabase opens an existing database for the report, trees
+// and info subcommands. A missing database file is an error directing
+// the user to run scan first; the schema version must match exactly.
+func openReportDatabase(ctx context.Context,
+	path string,
+) (*sql.DB, error) {
+	_, err := os.Stat(path)
+	if errors.Is(err, fs.ErrNotExist) {
+		return nil, fmt.Errorf("%s: %w", path, errNoDatabase)
+	}
+
+	if err != nil {
+		return nil, fmt.Errorf("database: %w", err)
+	}
+
+	db, err := openDB(path, reportParams)
+	if err != nil {
+		return nil, err
+	}
+
+	v, err := userVersion(ctx, db)
+	if err == nil && v == 0 {
+		// An empty database passes this check and fails the version
+		// check below.
+		err = checkUnversioned(ctx, db)
+	}
+
+	if err != nil {
+		_ = db.Close()
+
+		return nil, fmt.Errorf("database %s: %w", path, err)
+	}
+
+	if v != schemaVersion {
+		_ = db.Close()
+
+		return nil, fmt.Errorf("database %s: version %d, want %d: %w",
+			path, v, schemaVersion, errSchemaVersion)
+	}
+
+	return db, nil
+}
+
+// initSchema creates the schema on a fresh database and verifies the
+// schema version on an existing one.
+func initSchema(ctx context.Context, db *sql.DB) error {
+	v, err := userVersion(ctx, db)
+	if err != nil {
+		return err
+	}
+
+	switch v {
+	case 0:
+		err = checkUnversioned(ctx, db)
+		if err != nil {
+			return err
+		}
+
+		return createSchema(ctx, db)
+	case schemaVersion:
+		return nil
+	default:
+		return fmt.Errorf("version %d, want %d: %w",
+			v, schemaVersion, errSchemaVersion)
+	}
+}
+
+// checkUnversioned checks a database at user_version 0 before it is
+// taken for an empty one. createSchema creates the files table and
+// sets the version together, so a files table at version 0 was made by
+// something else. Adopting it could corrupt unrelated data, so that is
+// a schema-version error telling the operator to remove the file and
+// rescan.
+func checkUnversioned(ctx context.Context, db *sql.DB) error {
+	var name string
+
+	err := db.QueryRowContext(ctx,
+		"SELECT name FROM sqlite_master "+
+			"WHERE type = 'table' AND name = 'files'").Scan(&name)
+
+	switch {
+	case err == nil:
+		return fmt.Errorf(
+			"has a files table but no schema version; "+
+				"remove the file and rescan: %w", errSchemaVersion)
+	case errors.Is(err, sql.ErrNoRows):
+		return nil
+	default:
+		return fmt.Errorf("check for files table: %w", err)
+	}
+}
+
+// createSchema applies the schema to a fresh database and stamps the
+// schema version in one transaction, so a creation stopped partway, by
+// an interrupt or an error, leaves an empty database the next scan
+// sets up, never a files table at version 0, which checkUnversioned
+// refuses.
+func createSchema(ctx context.Context, db *sql.DB) error {
+	tx, err := db.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("create schema: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	for _, stmt := range []string{
+		createTableSQL, createIndexSQL, createTotalsSQL, insertTotalsSQL,
+		totalsAfterInsertSQL, totalsAfterDeleteSQL, totalsAfterUpdateSQL,
+	} {
+		_, err = tx.ExecContext(ctx, stmt)
+		if err != nil {
+			return fmt.Errorf("create schema: %w", err)
+		}
+	}
+
+	_, err = tx.ExecContext(ctx,
+		"PRAGMA user_version = "+strconv.Itoa(schemaVersion))
+	if err != nil {
+		return fmt.Errorf("set schema version: %w", err)
+	}
+
+	err = tx.Commit()
+	if err != nil {
+		return fmt.Errorf("create schema: %w", err)
+	}
+
+	return nil
+}
+
+// userVersion reads the database's PRAGMA user_version.
+func userVersion(ctx context.Context, db *sql.DB) (int, error) {
+	var v int
+
+	err := db.QueryRowContext(ctx, "PRAGMA user_version").Scan(&v)
+	if err != nil {
+		return 0, fmt.Errorf("read schema version: %w", err)
+	}
+
+	return v, nil
+}
+
+// loadFileRows gives total the number of records, then streams every
+// record to fn in path order: byte order, which is the order of the
+// primary key, so SQLite does not sort. The count and the records are
+// read in one transaction, so they agree while a scan is committing.
+func loadFileRows(ctx context.Context, db *sql.DB, total func(n int64),
+	fn func(r scanRec),
+) error {
+	// Everything goes through tx: db has one connection, so a query on
+	// db would wait for tx forever.
+	tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
+	if err != nil {
+		return fmt.Errorf("read records: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	var n int64
+
+	err = tx.QueryRowContext(ctx, recordCountSQL).Scan(&n)
+	if err != nil {
+		return fmt.Errorf("count records: %w", err)
+	}
+
+	total(n)
+
+	rows, err := tx.QueryContext(ctx,
+		"SELECT path, size, disk_size, mtime, mtime_nsec, head, tail, "+
+			"content FROM files ORDER BY path")
+	if err != nil {
+		return fmt.Errorf("read records: %w", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	for rows.Next() {
+		var (
+			path, head, tail, content []byte
+			sec, nsec                 int64
+			r                         scanRec
+		)
+
+		err = rows.Scan(&path, &r.size, &r.diskSize, &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)
+	}
+
+	err = rows.Err()
+	if err != nil {
+		return fmt.Errorf("read records: %w", err)
+	}
+
+	return nil
+}
+
+// signatureRowsSQL selects every record's signature and path in
+// signature order, largest size first. That is the order of the
+// files_signature index read backwards, so SQLite reads the index alone
+// and returns the first row at once, with nothing to sort.
+const signatureRowsSQL = `
+SELECT size, head, tail, content, path
+FROM files
+ORDER BY size DESC, head DESC, tail DESC, content DESC
+`
+
+// loadSignatureRows gives total the number of records, then streams
+// every record's signature and path to fn, without its mtime or its
+// disk_size, in the order of signatureRowsSQL. The count and the
+// records are read in one transaction, so they agree while a scan is
+// committing. An error from fn stops the reading and is returned as it
+// is.
+func loadSignatureRows(ctx context.Context, db *sql.DB,
+	total func(n int64), fn func(r scanRec) error,
+) error {
+	// Everything goes through tx: the report connection is the only
+	// one, so a query on db would wait for tx forever.
+	tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
+	if err != nil {
+		return fmt.Errorf("read records: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	var n int64
+
+	err = tx.QueryRowContext(ctx, recordCountSQL).Scan(&n)
+	if err != nil {
+		return fmt.Errorf("count records: %w", err)
+	}
+
+	total(n)
+
+	rows, err := tx.QueryContext(ctx, signatureRowsSQL)
+	if err != nil {
+		return fmt.Errorf("read records: %w", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	for rows.Next() {
+		var (
+			path, head, tail, content []byte
+			r                         scanRec
+		)
+
+		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
+		}
+	}
+
+	err = rows.Err()
+	if err != nil {
+		return fmt.Errorf("read records: %w", err)
+	}
+
+	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
+
+	err := db.QueryRowContext(ctx, recordCountSQL).Scan(&n)
+	if err != nil {
+		return 0, fmt.Errorf("count records: %w", err)
+	}
+
+	return n, nil
+}
+
+// databaseCountsSQL reads the number of records and the sizes of all
+// records added up from totals.
+const databaseCountsSQL = `
+SELECT records, size FROM totals
+`
+
+// databaseCounts is what info reads from the database: its schema
+// version and the counts of databaseCountsSQL.
+type databaseCounts struct {
+	schemaVersion int
+	records       int64 // every record
+	size          int64 // the sizes of all records added up
+}
+
+// readDatabaseCounts reads the schema version, then the counts of
+// databaseCountsSQL, in one read-only transaction, so both describe the
+// database at one moment while a scan is committing.
+func readDatabaseCounts(ctx context.Context,
+	db *sql.DB,
+) (databaseCounts, error) {
+	var c databaseCounts
+
+	// Everything goes through tx: the report connection is the only
+	// one, so a query on db would wait for tx forever.
+	tx, err := db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true})
+	if err != nil {
+		return c, fmt.Errorf("count records: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	err = tx.QueryRowContext(ctx, "PRAGMA user_version").
+		Scan(&c.schemaVersion)
+	if err != nil {
+		return c, fmt.Errorf("read schema version: %w", err)
+	}
+
+	err = tx.QueryRowContext(ctx, databaseCountsSQL).
+		Scan(&c.records, &c.size)
+	if err != nil {
+		return c, fmt.Errorf("count records: %w", err)
+	}
+
+	return c, nil
+}
+
+// loadFileMeta streams every record's path, size, disk_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, m fileMeta),
+) error {
+	rows, err := db.QueryContext(ctx,
+		"SELECT path, size, disk_size, mtime, mtime_nsec FROM files")
+	if err != nil {
+		return fmt.Errorf("read records: %w", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	for rows.Next() {
+		var (
+			path      []byte
+			m         fileMeta
+			sec, nsec int64
+		)
+
+		err = rows.Scan(&path, &m.size, &m.diskSize, &sec, &nsec)
+		if err != nil {
+			return fmt.Errorf("read record: %w", err)
+		}
+
+		m.mtime = time.Unix(sec, nsec)
+
+		fn(string(path), m)
+	}
+
+	err = rows.Err()
+	if err != nil {
+		return fmt.Errorf("read records: %w", err)
+	}
+
+	return nil
+}
+
+// updateBatchSize is the number of record changes committed per
+// transaction during the update pass. The filesystem is authoritative
+// and the database an eventually-consistent reflection of it, so
+// scan-level atomicity is not required; smaller transactions keep the
+// WAL small and let concurrent reports observe progress.
+const updateBatchSize = 10000
+
+// applyChanges writes upserts for new and changed files and deletes for
+// vanished ones, in batched transactions. Progress is rendered on prog
+// (one increment per change).
+func applyChanges(ctx context.Context, db *sql.DB, upserts []scanRec,
+	deletes []string, prog *progress,
+) error {
+	for batch := range slices.Chunk(upserts, updateBatchSize) {
+		err := applyBatch(ctx, db, batch, nil, nil, prog)
+		if err != nil {
+			return err
+		}
+	}
+
+	for batch := range slices.Chunk(deletes, updateBatchSize) {
+		err := applyBatch(ctx, db, nil, nil, batch, prog)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// applyDiskSizes writes the disk_size of each of recs into its record,
+// in batched transactions, and leaves the rest of the record alone.
+// Progress is rendered on prog (one increment per record).
+func applyDiskSizes(ctx context.Context, db *sql.DB, recs []fileRec,
+	prog *progress,
+) error {
+	for batch := range slices.Chunk(recs, updateBatchSize) {
+		err := applyBatch(ctx, db, nil, batch, nil, prog)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// applyBatch commits one batch of upserts, disk_size updates and
+// deletes in a single transaction.
+func applyBatch(ctx context.Context, db *sql.DB, upserts []scanRec,
+	diskSizes []fileRec, deletes []string, prog *progress,
+) error {
+	tx, err := db.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("begin transaction: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	err = execUpserts(ctx, tx, upserts, prog)
+	if err != nil {
+		return err
+	}
+
+	err = execDiskSizes(ctx, tx, diskSizes, prog)
+	if err != nil {
+		return err
+	}
+
+	err = execDeletes(ctx, tx, deletes, prog)
+	if err != nil {
+		return err
+	}
+
+	err = tx.Commit()
+	if err != nil {
+		return fmt.Errorf("commit: %w", err)
+	}
+
+	return nil
+}
+
+// execUpserts inserts or updates one record per new or changed file.
+func execUpserts(ctx context.Context, tx *sql.Tx, upserts []scanRec,
+	prog *progress,
+) error {
+	st, err := tx.PrepareContext(ctx, upsertSQL)
+	if err != nil {
+		return fmt.Errorf("prepare upsert: %w", err)
+	}
+
+	defer func() { _ = st.Close() }()
+
+	for _, r := range upserts {
+		_, err = st.ExecContext(ctx, []byte(r.path), r.size, r.diskSize,
+			r.mtime.Unix(), r.mtime.Nanosecond(),
+			r.head[:], r.tail[:], r.content[:])
+		if err != nil {
+			return fmt.Errorf("upsert %s: %w", r.path, err)
+		}
+
+		prog.increment()
+	}
+
+	return nil
+}
+
+// execDiskSizes sets the disk_size of the record of each of recs. It
+// does not touch size, so the totals triggers do not fire.
+func execDiskSizes(ctx context.Context, tx *sql.Tx, recs []fileRec,
+	prog *progress,
+) error {
+	st, err := tx.PrepareContext(ctx,
+		"UPDATE files SET disk_size = ? WHERE path = ?")
+	if err != nil {
+		return fmt.Errorf("prepare disk_size update: %w", err)
+	}
+
+	defer func() { _ = st.Close() }()
+
+	for _, r := range recs {
+		_, err = st.ExecContext(ctx, r.diskSize, []byte(r.path))
+		if err != nil {
+			return fmt.Errorf("update disk_size of %s: %w", r.path, err)
+		}
+
+		prog.increment()
+	}
+
+	return nil
+}
+
+// execDeletes removes the records for paths no longer present.
+func execDeletes(ctx context.Context, tx *sql.Tx, deletes []string,
+	prog *progress,
+) error {
+	st, err := tx.PrepareContext(ctx, "DELETE FROM files WHERE path = ?")
+	if err != nil {
+		return fmt.Errorf("prepare delete: %w", err)
+	}
+
+	defer func() { _ = st.Close() }()
+
+	for _, p := range deletes {
+		_, err = st.ExecContext(ctx, []byte(p))
+		if err != nil {
+			return fmt.Errorf("delete %s: %w", p, err)
+		}
+
+		prog.increment()
+	}
+
+	return nil
+}

internal/sfdupes/db_test.go

@@ -0,0 +1,824 @@
+package sfdupes //nolint:testpackage // calls the unexported database openers
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+)
+
+// testDBPath returns a database path inside a fresh temp dir, with
+// symlinks resolved as the scan lock resolves them, so the lock file
+// is this path plus ".lock" even where the temp dir is reached through
+// a symlink.
+func testDBPath(t *testing.T) string {
+	t.Helper()
+
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return filepath.Join(dir, "db.sqlite")
+}
+
+// openTestDB creates a fresh scan database in a temp dir.
+func openTestDB(t *testing.T) *sql.DB {
+	t.Helper()
+
+	db, err := openScanDatabase(t.Context(), testDBPath(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	return db
+}
+
+func TestDatabasePath(t *testing.T) {
+	// README §Database: SFDUPES_DATABASE when set and non-empty, the
+	// default otherwise, with the working directory, its symlinks
+	// resolved, put in front of a relative path. Nothing is cleaned, so
+	// a ".." stays.
+	dir, err := filepath.EvalSymlinks(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Chdir(dir)
+
+	fromEnv := "from " + databaseEnv
+	cases := []struct {
+		env, path, source string
+	}{
+		{"", defaultDatabasePath, "default"},
+		{"/custom/place.sqlite", "/custom/place.sqlite", fromEnv},
+		{"/custom/link/../place.sqlite", "/custom/link/../place.sqlite",
+			fromEnv},
+		{"sub/place.sqlite", dir + "/sub/place.sqlite", fromEnv},
+		{"link/../place.sqlite", dir + "/link/../place.sqlite", fromEnv},
+	}
+
+	for _, tc := range cases {
+		t.Setenv(databaseEnv, tc.env)
+
+		path, source, err := databasePath()
+		if err != nil || path != tc.path || source != tc.source {
+			t.Errorf("databasePath() with %s=%q = %q, %q, %v; want %q, %q",
+				databaseEnv, tc.env, path, source, err, tc.path, tc.source)
+		}
+	}
+
+	// In the root directory the path gets one slash in front, not two.
+	t.Chdir("/")
+	t.Setenv(databaseEnv, "place.sqlite")
+
+	path, _, err := databasePath()
+	if err != nil || path != "/place.sqlite" {
+		t.Errorf("databasePath() in / = %q, %v; want %q",
+			path, err, "/place.sqlite")
+	}
+}
+
+func TestOpenScanDatabaseCreates(t *testing.T) {
+	t.Parallel()
+
+	// The parent directory does not exist yet; scan must create it.
+	path := filepath.Join(t.TempDir(), "nested", "dir", "db.sqlite")
+
+	db, err := openScanDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatalf("openScanDatabase: %v", err)
+	}
+
+	v, err := userVersion(t.Context(), db)
+	if err != nil || v != schemaVersion {
+		t.Fatalf("userVersion = %d, %v; want %d, nil", v, err, schemaVersion)
+	}
+
+	_ = db.Close()
+
+	// Reopening an existing database must succeed and find the schema.
+	db, err = openScanDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatalf("reopen: %v", err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	if recs := dbRecords(t, db); len(recs) != 0 {
+		t.Fatalf("records = %v, want none", recs)
+	}
+}
+
+// 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()
+
+	// A database that has a files table but user_version 0, written by
+	// some other tool. report, trees and scan must refuse it with the
+	// schema-version error, not adopt it and not emit a raw SQLite
+	// "table files already exists".
+	path := testDBPath(t)
+
+	db, err := sql.Open("sqlite", path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.ExecContext(t.Context(), "CREATE TABLE files (x INTEGER)")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_ = db.Close()
+
+	_, err = openReportDatabase(t.Context(), path)
+	if !errors.Is(err, errSchemaVersion) ||
+		!strings.Contains(err.Error(), "remove the file and rescan") {
+		t.Fatalf("report: err = %v, want errSchemaVersion telling the "+
+			"operator to remove the file and rescan", err)
+	}
+
+	_, err = openScanDatabase(t.Context(), path)
+	if !errors.Is(err, errSchemaVersion) ||
+		!strings.Contains(err.Error(), "remove the file and rescan") {
+		t.Fatalf("scan: err = %v, want errSchemaVersion telling the "+
+			"operator to remove the file and rescan", err)
+	}
+}
+
+func TestSchemaCreationStoppedPartway(t *testing.T) {
+	t.Parallel()
+
+	// A first scan stopped while creating the schema must leave a
+	// database the next scan accepts. max_page_count(2) leaves room for
+	// the files table but not its index, so schema creation fails right
+	// after CREATE TABLE, a point an interrupt could also stop it at.
+	path := testDBPath(t)
+
+	db, err := openDB(path, scanParams+"&_pragma=max_page_count(2)")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = initSchema(t.Context(), db)
+	_ = db.Close()
+
+	if err == nil {
+		t.Fatal("initSchema with no room for the index succeeded")
+	}
+
+	db, err = openScanDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatalf("next scan: %v", err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	v, err := userVersion(t.Context(), db)
+	if err != nil || v != schemaVersion {
+		t.Fatalf("userVersion = %d, %v; want %d, nil", v, err, schemaVersion)
+	}
+}
+
+func TestOpenReportDatabaseMissing(t *testing.T) {
+	t.Parallel()
+
+	_, err := openReportDatabase(t.Context(), testDBPath(t))
+	if !errors.Is(err, errNoDatabase) {
+		t.Fatalf("err = %v, want errNoDatabase", err)
+	}
+}
+
+func TestOpenDatabaseVersionMismatch(t *testing.T) {
+	t.Parallel()
+
+	// A database stamped with a schema version other than 0 and
+	// schemaVersion. report, trees and scan must all refuse it.
+	path := testDBPath(t)
+
+	db, err := openScanDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.ExecContext(context.Background(), "PRAGMA user_version = 99")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_ = db.Close()
+
+	_, err = openReportDatabase(t.Context(), path)
+	if !errors.Is(err, errSchemaVersion) {
+		t.Fatalf("report: err = %v, want errSchemaVersion", err)
+	}
+
+	_, err = openScanDatabase(t.Context(), path)
+	if !errors.Is(err, errSchemaVersion) {
+		t.Fatalf("scan: err = %v, want errSchemaVersion", err)
+	}
+}
+
+func TestOpenReportDatabaseOK(t *testing.T) {
+	t.Parallel()
+
+	path := testDBPath(t)
+
+	db, err := openScanDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_ = db.Close()
+
+	db, err = openReportDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatalf("openReportDatabase: %v", err)
+	}
+
+	_ = db.Close()
+}
+
+func TestCloseScanDatabaseWhileReportOpen(t *testing.T) {
+	t.Parallel()
+
+	// A report holding the database open stops scan from taking it out
+	// of WAL mode. The -wal and -shm files must then stay beside it, so
+	// that a later report still needs only read access.
+	path := testDBPath(t)
+
+	scanDB, err := openScanDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	reportDB, err := openReportDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	closeScanDatabase(t.Context(), scanDB, path)
+
+	_ = reportDB.Close()
+
+	_, err = os.Stat(path + "-wal")
+	if err != nil {
+		t.Fatalf("no -wal left: the switch out of WAL mode was not "+
+			"stopped: %v", err)
+	}
+
+	makeReadOnly(t, path)
+
+	reportDB, err = openReportDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatalf("openReportDatabase: %v", err)
+	}
+
+	defer func() { _ = reportDB.Close() }()
+
+	err = loadFileRows(t.Context(), reportDB, func(int64) {},
+		func(scanRec) {})
+	if err != nil {
+		t.Fatalf("loadFileRows: %v", err)
+	}
+}
+
+// TestLoadRowsCountAgreeDuringScan has a scan commit records after
+// loadFileRows, as trees calls it, or loadSignatureRows, as report
+// calls it, has counted the records and before it reads them, as when
+// trees or report runs during a scan: each must read exactly as many
+// records as it counted.
+func TestLoadRowsCountAgreeDuringScan(t *testing.T) {
+	t.Parallel()
+
+	loads := map[string]func(context.Context, *sql.DB, func(int64),
+		func(scanRec)) error{
+		"loadFileRows": loadFileRows,
+		"loadSignatureRows": func(ctx context.Context, db *sql.DB,
+			total func(int64), fn func(scanRec),
+		) error {
+			return loadSignatureRows(ctx, db, total, func(r scanRec) error {
+				fn(r)
+
+				return nil
+			})
+		},
+	}
+
+	for name, load := range loads {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			path := testDBPath(t)
+
+			scanDB, err := openScanDatabase(t.Context(), path)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			defer func() { _ = scanDB.Close() }()
+
+			recs := smokeTreeRecs()
+
+			err = applyChanges(t.Context(), scanDB, recs[:3], nil, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			reportDB, err := openReportDatabase(t.Context(), path)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			defer func() { _ = reportDB.Close() }()
+
+			var counted, read int64
+
+			err = load(t.Context(), reportDB, func(n int64) {
+				counted = n
+
+				err := applyChanges(t.Context(), scanDB, recs[3:], nil, nil)
+				if err != nil {
+					t.Error(err)
+				}
+			}, func(scanRec) { read++ })
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			if counted != 3 || read != counted {
+				t.Errorf("counted %d records and read %d, want 3 and 3",
+					counted, read)
+			}
+		})
+	}
+}
+
+// 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)
+				}
+			}
+		})
+	}
+}
+
+// queryPlan returns the detail of each line of SQLite's EXPLAIN QUERY
+// PLAN for query.
+func queryPlan(t *testing.T, db *sql.DB, query string) []string {
+	t.Helper()
+
+	rows, err := db.QueryContext(t.Context(), "EXPLAIN QUERY PLAN "+query)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var plan []string
+
+	for rows.Next() {
+		var (
+			id, parent, unused int
+			detail             string
+		)
+
+		err = rows.Scan(&id, &parent, &unused, &detail)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		plan = append(plan, detail)
+	}
+
+	err = rows.Err()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return plan
+}
+
+// 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
+// record as it comes rather than waiting on SQLite for all of them.
+func TestSignatureRowsNeedNoSort(t *testing.T) {
+	t.Parallel()
+
+	db := openTestDB(t)
+
+	plan := queryPlan(t, db, signatureRowsSQL)
+
+	want := []string{"SCAN files USING COVERING INDEX files_signature"}
+	if !slices.Equal(plan, want) {
+		t.Errorf("query plan = %q, want %q", plan, want)
+	}
+}
+
+// TestCountsReadOnlyTotals checks that SQLite answers the queries for
+// the number of records and their total size from the one row of
+// totals. A plan that reads files or its index reads every record.
+func TestCountsReadOnlyTotals(t *testing.T) {
+	t.Parallel()
+
+	db := openTestDB(t)
+
+	for _, query := range []string{recordCountSQL, databaseCountsSQL} {
+		plan := queryPlan(t, db, query)
+
+		want := []string{"SCAN totals"}
+		if !slices.Equal(plan, want) {
+			t.Errorf("query plan of %q = %q, want %q", query, plan, want)
+		}
+	}
+}
+
+// TestCountsComeFromTotals sets the row of totals to numbers that files
+// does not hold, then checks that scan's load phase, the read phases of
+// trees and report, and info each report the numbers from totals.
+func TestCountsComeFromTotals(t *testing.T) {
+	t.Parallel()
+
+	// files is empty, so a count over files gives 0 records of 0 bytes.
+	const records, size = 7, 9000
+
+	db := openTestDB(t)
+
+	_, err := db.ExecContext(t.Context(),
+		"UPDATE totals SET records = ?, size = ?", records, size)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	scanTotal, err := countRecords(t.Context(), db)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var treesTotal, reportTotal int64
+
+	err = loadFileRows(t.Context(), db,
+		func(n int64) { treesTotal = n }, func(scanRec) {})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = loadSignatureRows(t.Context(), db,
+		func(n int64) { reportTotal = n },
+		func(scanRec) error { return nil })
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	info, err := readDatabaseCounts(t.Context(), db)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for name, got := range map[string]int64{
+		"scan's load":   scanTotal,
+		"trees' read":   treesTotal,
+		"report's read": reportTotal,
+		"info":          info.records,
+	} {
+		if got != records {
+			t.Errorf("%s: %d records, want %d from totals",
+				name, got, records)
+		}
+	}
+
+	if info.size != size {
+		t.Errorf("info: size %d, want %d from totals", info.size, size)
+	}
+}
+
+// assertTotalsMatchFiles fails unless the row of totals holds the
+// number of records and the sizes of all records added up, as counted
+// over files.
+func assertTotalsMatchFiles(t *testing.T, db *sql.DB) {
+	t.Helper()
+
+	got, err := readDatabaseCounts(t.Context(), db)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var records, size int64
+
+	err = db.QueryRowContext(t.Context(),
+		"SELECT COUNT(*), COALESCE(SUM(size), 0) FROM files").
+		Scan(&records, &size)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if got.records != records || got.size != size {
+		t.Errorf("totals = %d records of %d bytes, files holds %d of %d",
+			got.records, got.size, records, size)
+	}
+}
+
+// TestTotalsMatchFiles scans the smoke tree, rescans it after two files
+// change size, and rescans it after two files are removed. After each
+// scan the row of totals must agree with files.
+func TestTotalsMatchFiles(t *testing.T) {
+	t.Parallel()
+
+	dir := buildSmokeTree(t)
+	db := openTestDB(t)
+
+	syncTree(t, db, dir)
+	assertTotalsMatchFiles(t, db)
+
+	writeFile(t, dir, "a/one.bin", pattern(10, 2500))
+	writeFile(t, dir, "t1/f1", pattern(30, 1000))
+
+	if st := syncTree(t, db, dir); st.updated != 2 {
+		t.Fatalf("rescan stats = %+v, want 2 updated", st)
+	}
+
+	assertTotalsMatchFiles(t, db)
+
+	for _, name := range []string{"a/unique.bin", "t2/sub/f2"} {
+		err := os.Remove(filepath.Join(dir, name))
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	if st := syncTree(t, db, dir); st.removed != 2 {
+		t.Fatalf("rescan stats = %+v, want 2 removed", st)
+	}
+
+	assertTotalsMatchFiles(t, db)
+}
+
+func TestApplyChangesRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	db := openTestDB(t)
+
+	// Paths may contain tabs and newlines; the database must store
+	// them byte-exactly. Every hash, content included, comes back as
+	// written.
+	recs := []scanRec{
+		{
+			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: testHash("h1"),
+			tail: testHash("t1"), content: testHash("c1"), path: "/a/x",
+		},
+	}
+
+	prog := newProgress(progressParams{label: "update", total: 4})
+	defer prog.finish()
+
+	err := applyChanges(t.Context(), db, recs, nil, prog)
+	if err != nil {
+		t.Fatalf("applyChanges: %v", err)
+	}
+
+	// The records come back in path order, which is the order of recs.
+	got := dbRecords(t, db)
+	if !slices.Equal(got, recs) {
+		t.Fatalf("rows = %+v, want %+v", got, recs)
+	}
+
+	// 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: testHash("h3"),
+		tail: testHash("t3"), content: testHash("c3"), path: "/a/x",
+	}
+
+	err = applyChanges(t.Context(), db, []scanRec{upd},
+		[]string{"/a/tab\tnew\nline"}, prog)
+	if err != nil {
+		t.Fatalf("applyChanges: %v", err)
+	}
+
+	got = dbRecords(t, db)
+	if len(got) != 1 || got[0] != upd {
+		t.Fatalf("rows = %+v, want just %+v", got, upd)
+	}
+}
+
+func TestApplyChangesBatching(t *testing.T) {
+	t.Parallel()
+
+	db := openTestDB(t)
+
+	// One more change than the batch size, so the update spans two
+	// transactions.
+	n := updateBatchSize + 1
+
+	recs := make([]scanRec, 0, n)
+	for i := range n {
+		recs = append(recs, scanRec{
+			size: int64(i), mtime: time.Unix(1, 0), head: testHash("h"),
+			tail: testHash("t"), path: fmt.Sprintf("/batch/%07d", i),
+		})
+	}
+
+	prog := newProgress(progressParams{label: "update", total: int64(2 * n)})
+	defer prog.finish()
+
+	err := applyChanges(t.Context(), db, recs, nil, prog)
+	if err != nil {
+		t.Fatalf("applyChanges: %v", err)
+	}
+
+	if got := dbRecords(t, db); len(got) != n {
+		t.Fatalf("records = %d, want %d", len(got), n)
+	}
+
+	deletes := make([]string, 0, n)
+	for _, r := range recs {
+		deletes = append(deletes, r.path)
+	}
+
+	err = applyChanges(t.Context(), db, nil, deletes, prog)
+	if err != nil {
+		t.Fatalf("applyChanges deletes: %v", err)
+	}
+
+	if got := dbRecords(t, db); len(got) != 0 {
+		t.Fatalf("records = %d, want 0", len(got))
+	}
+}

internal/sfdupes/dwim.go

@@ -0,0 +1,37 @@
+package sfdupes
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"runtime"
+)
+
+// runDwim implements the dwim subcommand: it runs what "sfdupes scan
+// root" runs with no flags, then what "sfdupes trees" runs, and ends
+// with a line on stderr saying how to print the report again. The dwim
+// command passes "/" as root. It catches SIGINT and SIGTERM as scan
+// does, but only during the scan. An error from the scan, an interrupt
+// included, ends it before the report. During the report, a signal
+// ends it at once, as it ends trees.
+func runDwim(ctx context.Context, root string, stdout io.Writer) error {
+	scanCtx, stop := interruptContext(ctx)
+	err := runScan(scanCtx, []string{root}, runtime.NumCPU(), false, false)
+
+	stop()
+
+	if err != nil {
+		return err
+	}
+
+	err = runTrees(ctx, stdout)
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintln(os.Stderr,
+		`dwim: run "sfdupes trees" to print this report again`)
+
+	return nil
+}

internal/sfdupes/dwim_test.go

@@ -0,0 +1,83 @@
+package sfdupes //nolint:testpackage // calls the unexported runDwim
+
+import (
+	"bytes"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestRunDwimPrintsLargestTreesFirst(t *testing.T) {
+	// dwim scans its root, then prints the trees report, the larger of
+	// two duplicate-tree pairs first, and ends by saying how to print
+	// the report again.
+	t.Setenv(databaseEnv, testDBPath(t))
+
+	root := realTempDir(t)
+
+	small := []string{
+		filepath.Dir(writeFile(t, root, "a1/f.bin", pattern(1, 300))),
+		filepath.Dir(writeFile(t, root, "a2/f.bin", pattern(1, 300))),
+	}
+	large := []string{
+		filepath.Dir(writeFile(t, root, "b1/f.bin", pattern(2, 5000))),
+		filepath.Dir(writeFile(t, root, "b2/f.bin", pattern(2, 5000))),
+	}
+
+	var stdout bytes.Buffer
+
+	stderr := captureStderr(t)
+
+	err := runDwim(t.Context(), root, &stdout)
+	if err != nil {
+		t.Fatalf("runDwim: %v; stderr: %s", err, stderr())
+	}
+
+	lines := strings.Split(strings.TrimSuffix(stdout.String(), "\n"), "\n")
+	if len(lines) != 3 {
+		t.Fatalf("stdout = %q, want a header and two groups",
+			stdout.String())
+	}
+
+	wantFirst := large[0] + "\t" + large[1] + "\t1\t5000\t"
+	if !strings.HasPrefix(lines[1], wantFirst) {
+		t.Errorf("first group = %q, want it to start %q", lines[1], wantFirst)
+	}
+
+	wantSecond := small[0] + "\t" + small[1] + "\t1\t300\t"
+	if !strings.HasPrefix(lines[2], wantSecond) {
+		t.Errorf("second group = %q, want it to start %q",
+			lines[2], wantSecond)
+	}
+
+	last := "\ndwim: run \"sfdupes trees\" to print this report again\n"
+	if got := stderr(); !strings.HasSuffix(got, last) {
+		t.Errorf("stderr = %q, want it to end %q", got, last)
+	}
+}
+
+func TestRunDwimScanErrorPrintsNoReport(t *testing.T) {
+	// A fatal scan error ends dwim before the report: a root that does
+	// not exist fails the scan as it fails scan itself.
+	t.Setenv(databaseEnv, testDBPath(t))
+
+	missing := filepath.Join(realTempDir(t), "missing")
+
+	var stdout bytes.Buffer
+
+	stderr := captureStderr(t)
+
+	err := runDwim(t.Context(), missing, &stdout)
+	if err == nil {
+		t.Fatal("runDwim on a missing root: error = nil, want it fatal")
+	}
+
+	if got := stdout.String(); got != "" {
+		t.Errorf("stdout = %q, want no report", got)
+	}
+
+	if got := stderr(); strings.Contains(got, "trees:") ||
+		strings.Contains(got, "dwim:") {
+		t.Errorf("stderr = %q, want nothing from trees or dwim", got)
+	}
+}

internal/sfdupes/exclude.go

@@ -0,0 +1,195 @@
+package sfdupes
+
+// 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()
+}

internal/sfdupes/exclude_darwin.go

@@ -0,0 +1,52 @@
+//go:build darwin
+
+package sfdupes
+
+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
+}

internal/sfdupes/exclude_other.go

@@ -0,0 +1,36 @@
+//go:build !darwin
+
+package sfdupes
+
+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
+}

internal/sfdupes/exclude_test.go

@@ -0,0 +1,515 @@
+package sfdupes //nolint:testpackage // checks the unexported defaultExcludes
+
+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": the Linux and macOS lists, and none
+	// on any other system. The Windows list exists in the code only: the
+	// binary does not build for Windows, so the README leaves it out.
+	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 := realTempDir(t)
+	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)
+	}
+}

internal/sfdupes/info.go

@@ -0,0 +1,125 @@
+package sfdupes
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+// infoPhase names one phase of info with its place among all of them,
+// as "[2/2] count", for the phase's progress display. The list here is
+// the one place the phases are counted.
+func infoPhase(name string) string {
+	return phaseLabel([]string{openPhase, "count"}, name)
+}
+
+// runInfo implements the info subcommand: it prints the database's
+// details on stdout (see writeInfo). It opens the database as report
+// does, read-only and without the scan lock, and never touches the
+// scanned filesystem. It names the database on stderr before it opens
+// it. Any database problem, including a missing database, is fatal.
+//
+// The work runs in two phases, each under a progress display of its
+// own on stderr: open (open the database) and count (read the number of
+// records and their total size from the totals table). Each display
+// ends before the next phase starts, and before an error is returned
+// to be printed. The details are written once the last display has
+// ended, so no display is drawn while they are written.
+func runInfo(ctx context.Context, stdout io.Writer) error {
+	dbPath, source, err := databasePath()
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(os.Stderr, "info: database %s (%s)\n",
+		escapePath(dbPath), source)
+
+	// Opening can wait on a busy database for as long as the busy
+	// timeout.
+	prog := newProgress(progressParams{
+		label: infoPhase(openPhase), total: -1,
+		waitingFor: openingDatabase,
+	})
+	db, err := openReportDatabase(ctx, dbPath)
+
+	prog.finish()
+
+	if err != nil {
+		return err
+	}
+
+	defer func() { _ = db.Close() }()
+
+	// One row holds both counts, so the phase never has a total.
+	prog = newProgress(progressParams{
+		label: infoPhase("count"), total: -1,
+		waitingFor: countingRecords,
+	})
+	counts, err := readDatabaseCounts(ctx, db)
+
+	prog.finish()
+
+	if err != nil {
+		return fmt.Errorf("database %s: %w", dbPath, err)
+	}
+
+	return writeInfo(stdout, dbPath, source, counts)
+}
+
+// writeInfo writes the details of the database at dbPath to stdout,
+// one per line, as a name, a tab and the value (README "`info` mode"):
+// the path and source as databasePath returns them, the sizes of the
+// database file and of its -wal file when there is one, when the
+// database file was last changed, and the schema version and record
+// counts that readDatabaseCounts read.
+func writeInfo(stdout io.Writer, dbPath, source string,
+	counts databaseCounts,
+) error {
+	// SQLite keeps the -wal file beside the database file, named from
+	// its path with symlinks resolved.
+	file, err := filepath.EvalSymlinks(dbPath)
+	if err != nil {
+		return fmt.Errorf("database: %w", err)
+	}
+
+	dbFile, err := os.Stat(file)
+	if err != nil {
+		return fmt.Errorf("database: %w", err)
+	}
+
+	walFile, err := os.Stat(file + "-wal")
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return fmt.Errorf("database: %w", err)
+	}
+
+	var b strings.Builder
+
+	fmt.Fprintf(&b, "database\t%s (%s)\n", escapePath(dbPath), source)
+	fmt.Fprintf(&b, "database file size\t%d (%s)\n",
+		dbFile.Size(), humanBytes(dbFile.Size()))
+
+	if walFile != nil {
+		fmt.Fprintf(&b, "-wal file size\t%d (%s)\n",
+			walFile.Size(), humanBytes(walFile.Size()))
+	}
+
+	fmt.Fprintf(&b, "modified\t%s\n",
+		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, "size of recorded files\t%d (%s)\n",
+		counts.size, humanBytes(counts.size))
+
+	_, err = io.WriteString(stdout, b.String())
+	if err != nil {
+		return fmt.Errorf("write stdout: %w", err)
+	}
+
+	return nil
+}

internal/sfdupes/info_test.go

@@ -0,0 +1,166 @@
+package sfdupes //nolint:testpackage // seeds the database with unexported scanRec
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// 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, " +
+	"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, " +
+	"remain unknown"
+
+// 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: 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"},
+	}
+}
+
+// TestRunInfo runs info on an empty and on a filled database, with
+// stdout and stderr the same file that is not a terminal, and checks
+// everything written there: the line naming the database, each phase's
+// line as it starts and as it ends, and then the details, each on a
+// line of its own. No -wal file is beside a database scan has closed.
+func TestRunInfo(t *testing.T) {
+	cases := map[string]struct {
+		recs []scanRec
+		want string // the details after the database file's time
+	}{
+		"empty": {
+			want: "schema version\t1\n" +
+				"records\t0\n" +
+				"size of recorded files\t0 (0 B)\n",
+		},
+		"filled": {
+			recs: infoRecs(),
+			want: "schema version\t1\n" +
+				"records\t4\n" +
+				"size of recorded files\t20971537 (20.0 MiB)\n",
+		},
+	}
+
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			path := seedDatabase(t, tc.recs)
+			t.Setenv(databaseEnv, path)
+
+			file, err := os.Stat(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			stderr := captureStderr(t)
+
+			code := run([]string{cmdInfo}, os.Stderr, os.Stderr)
+			if code != exitOK {
+				t.Fatalf("run(info) = %d, want %d; stderr: %s",
+					code, exitOK, stderr())
+			}
+
+			named := path + " (from " + databaseEnv + ")\n"
+			want := "info: database " + named +
+				infoOpenLine + "\n" + infoOpenLine + "\n" +
+				infoCountLine + "\n" + infoCountLine + "\n" +
+				"database\t" + named +
+				fmt.Sprintf("database file size\t%d (%s)\n",
+					file.Size(), humanBytes(file.Size())) +
+				"modified\t" + file.ModTime().UTC().Format(time.RFC3339) +
+				"\n" + tc.want
+
+			if got := stderr(); got != want {
+				t.Errorf("stdout and stderr = %q, want %q", got, want)
+			}
+		})
+	}
+}
+
+// TestRunInfoDuringScan runs info while a scan holds the lock and has
+// the database open in WAL mode, with records committed to the -wal
+// file only. info must count those records and show the -wal file's
+// size, also when the database path is a symlink: SQLite keeps the
+// -wal file beside the symlink's target.
+func TestRunInfoDuringScan(t *testing.T) {
+	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(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	err = applyChanges(t.Context(), db, infoRecs(), nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	holdScanLock(t, path)
+
+	wal, err := os.Stat(path + "-wal")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for _, named := range []string{path, link} {
+		t.Run(filepath.Base(named), func(t *testing.T) {
+			t.Setenv(databaseEnv, named)
+
+			stdout := runStdout(t, cmdInfo)
+
+			for _, want := range []string{
+				"database\t" + named + " (from " + databaseEnv + ")\n",
+				fmt.Sprintf("\n-wal file size\t%d (%s)\n",
+					wal.Size(), humanBytes(wal.Size())),
+				"\nrecords\t4\n",
+			} {
+				if !strings.Contains(stdout, want) {
+					t.Errorf("stdout = %q, want it to hold %q", stdout, want)
+				}
+			}
+		})
+	}
+}
+
+func TestRunInfoNeedsOnlyReadAccess(t *testing.T) {
+	// README "`info` mode": like report, info needs only read access to
+	// the database file and none to its directory.
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	scanFixture(t)
+	makeReadOnly(t, path)
+
+	stdout := runStdout(t, cmdInfo)
+
+	if want := "\nrecords\t2\n"; !strings.Contains(stdout, want) {
+		t.Errorf("stdout = %q, want it to hold %q", stdout, want)
+	}
+
+	if strings.Contains(stdout, "-wal") {
+		t.Errorf("stdout = %q, want no -wal file between scans", stdout)
+	}
+}

internal/sfdupes/progress.go

@@ -0,0 +1,558 @@
+package sfdupes
+
+import (
+	"fmt"
+	"io"
+	"math"
+	"os"
+	"slices"
+	"strings"
+	"sync"
+	"time"
+	"unicode/utf8"
+
+	"github.com/schollz/progressbar/v3"
+	"golang.org/x/term"
+)
+
+// plainInterval is the time between progress lines while a phase runs,
+// when stderr is not a TTY.
+const plainInterval = 5 * time.Second
+
+// redrawInterval is the time between redraws of the progress display on
+// 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 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
+
+// fallbackWidth is the width taken for a terminal whose width cannot be
+// read, as the progressbar library takes it.
+const fallbackWidth = 80
+
+// 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
+
+// countingRecords is what the display of a phase that reads the records
+// says until it has the number of records, its total.
+const countingRecords = "counting the records"
+
+// openPhase is the name of the phase in which report, trees and info
+// open the database, and openingDatabase what its display says while
+// it does.
+const (
+	openPhase       = "open"
+	openingDatabase = "opening the database"
+)
+
+// stderrIsTTY reports whether stderr is attached to a terminal.
+func stderrIsTTY() bool {
+	return term.IsTerminal(int(os.Stderr.Fd()))
+}
+
+// terminalWidth returns the width of the terminal on stderr, or
+// fallbackWidth, as the progressbar library does, when it cannot read
+// one.
+func terminalWidth() int {
+	width, _, err := term.GetSize(int(os.Stderr.Fd()))
+	if err != nil || width <= 0 {
+		return fallbackWidth
+	}
+
+	return width
+}
+
+// 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)
+}
+
+// progressParams describe one phase's progress display as it starts.
+type progressParams struct {
+	label      string // the phase and its place, from phaseLabel
+	unit       string // what the phase counts, as "files"
+	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 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
+// *progress is a valid no-display receiver: every method is a no-op, so
+// batched database flushes during the hash phase can reuse the update
+// phase's helpers without rendering anything, and its writer writes
+// with no display to clear.
+type progress struct {
+	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
+	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 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, time.Now)
+	}
+
+	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. The display reads the time by calling now.
+func startProgress(params progressParams, width func() int,
+	interval time.Duration, now func() time.Time,
+) *progress {
+	start := now()
+	p := &progress{
+		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,
+		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,
+	// and a phase must never look hung.
+	p.draw()
+
+	go func() {
+		defer close(p.done)
+
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+
+		for {
+			select {
+			case <-p.stop:
+				return
+			case <-ticker.C:
+				p.draw()
+			}
+		}
+	}()
+
+	return p
+}
+
+// draw shows the phase's progress: on a TTY in place of the 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 {
+		fmt.Fprintln(os.Stderr, p.line(now, math.MaxInt, false))
+
+		return
+	}
+
+	width := p.width()
+	text := p.line(now, width-spinnerMargin, true)
+
+	// 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 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: 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
+		// own erase is as wide as the widest line it drew.
+		blank := strings.Repeat(" ", min(p.widest, width-1))
+		fmt.Fprint(os.Stderr, "\r"+blank+"\r")
+	}
+
+	// A total of -1 gives the library's spinner.
+	p.bar = progressbar.NewOptions64(-1,
+		progressbar.OptionSetWriter(os.Stderr),
+		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 time remaining.
+		progressbar.OptionSetElapsedTime(false),
+		progressbar.OptionSetPredictTime(false),
+	)
+	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, 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, p.lastItem = now, now
+	p.drawn = []drawnCount{{at: now, count: p.count}}
+}
+
+// increment records one completed item, which the display shows at its
+// next draw.
+func (p *progress) increment() {
+	if p == nil {
+		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
+// display. The whole message is escaped like a report's path columns,
+// so a path holding a newline cannot split the warning.
+func (p *progress) warnf(format string, args ...any) {
+	if p == nil {
+		return
+	}
+
+	msg := escapePath(fmt.Sprintf(format, args...))
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if p.bar != nil {
+		// The warning takes the display's line; the next draw shows
+		// the display again, on the line below.
+		_ = p.bar.Clear()
+	}
+
+	fmt.Fprintln(os.Stderr, msg)
+}
+
+// progressWriter writes a phase's output to out, which may be the file
+// the phase's display is drawn on, as stdout is in a plain "sfdupes
+// trees" on a terminal. It holds what is written to it and writes that
+// to out in pieces of about ioBufSize bytes. When out is the file
+// stderr is, each piece is written under the display's lock with the
+// display cleared first, as warnf does for a warning: no draw lands in
+// the middle of a piece, and the next draw shows the display again, on
+// the line below. Every write to it must end with a newline, as a row
+// written with one fmt.Fprintf does, so that each piece ends a line.
+// Flush writes what it holds once the last row is written.
+type progressWriter struct {
+	// p is the display to clear, nil unless out is the file stderr is.
+	p   *progress
+	out io.Writer
+	buf []byte
+}
+
+// writer returns a progressWriter writing to out around p's display.
+// It clears the display and takes its lock only when out is the file
+// stderr is: the same device and inode, as os.SameFile compares them,
+// which is one terminal, or one pipe or file that both are sent to.
+// Otherwise it writes to out without the lock, so the display keeps
+// being drawn while a write to out waits for a slow reader.
+func (p *progress) writer(out io.Writer) *progressWriter {
+	w := &progressWriter{out: out}
+
+	if f, ok := out.(*os.File); ok {
+		outInfo, outErr := f.Stat()
+		errInfo, errErr := os.Stderr.Stat()
+
+		if outErr == nil && errErr == nil && os.SameFile(outInfo, errInfo) {
+			w.p = p
+		}
+	}
+
+	return w
+}
+
+// Write holds b, and writes what it holds to out once that comes to
+// ioBufSize bytes.
+func (w *progressWriter) Write(b []byte) (int, error) {
+	w.buf = append(w.buf, b...)
+	if len(w.buf) < ioBufSize {
+		return len(b), nil
+	}
+
+	return len(b), w.Flush()
+}
+
+// Flush writes what w holds to out. When out is the file stderr is, the
+// display is cleared first and not drawn again until it is written.
+func (w *progressWriter) Flush() error {
+	if w.p != nil {
+		w.p.mu.Lock()
+		defer w.p.mu.Unlock()
+
+		if w.p.bar != nil {
+			_ = w.p.bar.Clear()
+		}
+	}
+
+	_, err := w.out.Write(w.buf)
+	w.buf = w.buf[:0]
+
+	return err
+}
+
+// finish ends the phase's display, drawn once more as the phase ends.
+// A phase stopped short of its total, as an interrupted one is, shows
+// the count it stopped at rather than a full bar.
+func (p *progress) finish() {
+	if p == nil {
+		return
+	}
+
+	close(p.stop)
+	<-p.done
+
+	p.draw()
+
+	if p.width != nil {
+		// The display stays on the TTY as drawn; what follows starts
+		// on a line of its own.
+		fmt.Fprintln(os.Stderr)
+	}
+}
+
+// line formats the phase's progress as of now in at most room columns,
+// as
+//
+//	[3/4] hash: [1234/5000] 25%, 300 files/s, elapsed 4s, remain 13s
+//
+// 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".
+//
+// 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, remain unknown", elapsed)
+	} else {
+		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(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 + ", "
+		}
+	}
+
+	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
+	case len(kept) <= room:
+		return kept
+	}
+
+	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 "~"
+// before a total that is an estimate and without the percent when
+// percent is false, or as "1234 files", in the phase's unit, when the
+// phase has no total. p.mu must be held.
+func (p *progress) itemsDone(percent bool) string {
+	if p.total < 0 {
+		return fmt.Sprintf("%d %s", p.count, p.unit)
+	}
+
+	approx := ""
+	if p.estimate {
+		approx = "~"
+	}
+
+	done := fmt.Sprintf("[%d/%s%d]", p.count, approx, p.total)
+	if !percent {
+		return done
+	}
+
+	pct := float64(percentScale)
+	if p.total > 0 {
+		pct = percentScale * float64(p.count) / float64(p.total)
+	}
+
+	return fmt.Sprintf("%s %.0f%%", done, pct)
+}
+
+// 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) remain(rate float64) string {
+	switch {
+	case p.total < 0, p.estimate && p.count > p.total:
+		return "unknown"
+	case p.count >= p.total:
+		return "0s"
+	case rate <= 0:
+		return "unknown"
+	}
+
+	left := time.Duration(
+		float64(p.total-p.count) / rate * float64(time.Second))
+
+	return left.Round(time.Second).String()
+}

internal/sfdupes/report.go

@@ -0,0 +1,277 @@
+package sfdupes
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"fmt"
+	"io"
+	"os"
+	"slices"
+	"strings"
+	"time"
+)
+
+// ioBufSize is the buffer size for the buffered stdout writers.
+const ioBufSize = 1 << 20
+
+// minGroupSize is the smallest number of members that makes a
+// duplicate group.
+const minGroupSize = 2
+
+// scanRec is one file record from the database. The signature (size,
+// head, tail, content) is the duplicate key; mtime is informational
+// only and used by scan for change detection. diskSize is the bytes the
+// file takes on disk, which trees adds up.
+type scanRec struct {
+	size     int64
+	diskSize int64
+	mtime    time.Time
+	head     [sha256.Size]byte
+	tail     [sha256.Size]byte
+	content  [sha256.Size]byte
+	path     string
+}
+
+// reportPhase names one phase of report with its place among all of
+// them, as "[2/2] read", for the phase's progress display. The list
+// here is the one place the phases are counted.
+func reportPhase(name string) string {
+	return phaseLabel([]string{openPhase, "read"}, name)
+}
+
+// runReport implements the report subcommand: it prints the file-level
+// duplicates report as TSV on stdout. It never touches the scanned
+// filesystem; its only I/O is the database, stdout, and stderr. It
+// names the database on stderr before it opens it. Any database
+// problem, including a missing database, is fatal.
+//
+// The work runs in two phases, each under a progress display of its
+// own on stderr: open (open the database) and read (read the number of
+// records from the totals table, then read the records in signature
+// order, writing each size's duplicate groups to stdout once that size
+// is read; see readReport). Each display ends before the next phase
+// starts, and before an error is returned to be printed.
+func runReport(ctx context.Context, stdout io.Writer) error {
+	dbPath, source, err := databasePath()
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(os.Stderr, "report: database %s (%s)\n",
+		escapePath(dbPath), source)
+
+	// Opening can wait on a busy database for as long as the busy
+	// timeout.
+	prog := newProgress(progressParams{
+		label: reportPhase(openPhase), total: -1,
+		waitingFor: openingDatabase,
+	})
+	db, err := openReportDatabase(ctx, dbPath)
+
+	prog.finish()
+
+	if err != nil {
+		return err
+	}
+
+	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, stalledOn: "db/out",
+	})
+	report, err := readReport(ctx, db, dbPath, stdout, prog)
+
+	prog.finish()
+
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(os.Stderr,
+		"report: %d records read, %d duplicate groups, %d dupe files, "+
+			"%s reclaimable\n",
+		report.records, report.dupeGroups, report.dupeFiles,
+		humanBytes(report.reclaimable))
+
+	return nil
+}
+
+// readReport gives prog the number of records in db, the database at
+// dbPath, as its total, then reads every record in signature order,
+// counting each on prog, and writes the report to stdout: the header
+// line, then the rows of each size's duplicate groups once that size is
+// read. stdout may be the terminal prog is drawn on, so the lines go
+// through prog's writer. It returns what it wrote, with the totals for
+// the summary line.
+func readReport(ctx context.Context, db *sql.DB, dbPath string,
+	stdout io.Writer, prog *progress,
+) (*reportWriter, error) {
+	out := prog.writer(stdout)
+	report := &reportWriter{out: out}
+
+	_, err := fmt.Fprintln(out, "first\tdupe\tsize")
+	if err != nil {
+		return nil, fmt.Errorf("write stdout: %w", err)
+	}
+
+	var writeErr error
+
+	err = loadSignatureRows(ctx, db, prog.setTotal, func(r scanRec) error {
+		prog.increment()
+
+		writeErr = report.add(r)
+
+		return writeErr
+	})
+
+	if writeErr != nil {
+		return nil, fmt.Errorf("write stdout: %w", writeErr)
+	}
+
+	if err != nil {
+		return nil, fmt.Errorf("database %s: %w", dbPath, err)
+	}
+
+	err = report.finish()
+	if err == nil {
+		err = out.Flush()
+	}
+
+	if err != nil {
+		return nil, fmt.Errorf("write stdout: %w", err)
+	}
+
+	return report, nil
+}
+
+// reportWriter writes the report's rows to out from the records, added
+// in signature order, largest size first, as loadSignatureRows reads
+// them. The records sharing a signature come together, and so do the
+// records of one size, so it holds only the duplicate groups of the
+// size being read, and writes them, ordered by first path, once a
+// record of a smaller size comes. It counts what the summary line
+// reports.
+type reportWriter struct {
+	out io.Writer
+
+	sig    scanRec    // the signature being read; its path is not used
+	paths  []string   // the paths read so far with sig
+	groups [][]string // the duplicate groups of sig.size, each sorted
+
+	records, dupeGroups, dupeFiles int
+	reclaimable                    int64
+}
+
+// add takes the next record. One with the signature being read joins
+// its paths; any other ends them, and one of a smaller size first
+// writes the groups of the size before.
+func (w *reportWriter) add(r scanRec) error {
+	w.records++
+
+	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)
+
+		return nil
+	}
+
+	w.endGroup()
+
+	if r.size != w.sig.size {
+		err := w.writeGroups()
+		if err != nil {
+			return err
+		}
+	}
+
+	w.sig = r
+	w.paths = append(w.paths, r.path)
+
+	return nil
+}
+
+// endGroup ends the paths read with w.sig: two or more are a duplicate
+// group, held with its paths sorted until writeGroups writes it.
+func (w *reportWriter) endGroup() {
+	if len(w.paths) < minGroupSize {
+		// A path with no duplicate is dropped, and its slice reused.
+		w.paths = w.paths[:0]
+
+		return
+	}
+
+	slices.Sort(w.paths)
+	w.groups = append(w.groups, w.paths)
+	w.paths = nil
+}
+
+// writeGroups writes the duplicate groups held, all of size w.sig.size,
+// ordered by first path: for each group, a row for every path but the
+// first. No two groups share a first path, since no two records share
+// a path.
+func (w *reportWriter) writeGroups() error {
+	slices.SortFunc(w.groups, func(a, b []string) int {
+		return strings.Compare(a[0], b[0])
+	})
+
+	for _, g := range w.groups {
+		for _, path := range g[1:] {
+			_, err := fmt.Fprintf(w.out, "%s\t%s\t%d\n",
+				escapePath(g[0]), escapePath(path), w.sig.size)
+			if err != nil {
+				return err
+			}
+
+			w.dupeFiles++
+			w.reclaimable += w.sig.size
+		}
+
+		w.dupeGroups++
+	}
+
+	w.groups = nil
+
+	return nil
+}
+
+// finish writes the groups of the last size read.
+func (w *reportWriter) finish() error {
+	w.endGroup()
+
+	return w.writeGroups()
+}
+
+// escapePath returns a path as it is written in a report column (README
+// "Report output format"): a backslash, tab, newline or carriage return
+// becomes \\, \t, \n or \r, and every other byte is kept as it is.
+// Grouping and sorting use the raw path, never this form.
+func escapePath(p string) string {
+	// Most paths need no escaping; skip building a replacer for them.
+	if !strings.ContainsAny(p, "\\\t\n\r") {
+		return p
+	}
+
+	return strings.NewReplacer(
+		`\`, `\\`, "\t", `\t`, "\n", `\n`, "\r", `\r`,
+	).Replace(p)
+}
+
+// humanBytes formats a byte count in human units (binary prefixes).
+func humanBytes(n int64) string {
+	const unit = 1024
+	if n < unit {
+		return fmt.Sprintf("%d B", n)
+	}
+
+	div, exp := int64(unit), 0
+	for m := n / unit; m >= unit; m /= unit {
+		div *= unit
+		exp++
+	}
+
+	return fmt.Sprintf("%.1f %ciB", float64(n)/float64(div), "KMGTPE"[exp])
+}

internal/sfdupes/report_test.go

@@ -0,0 +1,588 @@
+package sfdupes //nolint:testpackage // checks the unexported dupeGroup results
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"database/sql"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"slices"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// 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, diskSize: 4096, head: h, tail: tl, content: c, path: "/d/A/f"},
+		{size: 5, diskSize: 4096, head: h, tail: tl, content: c, path: awkwardDir + "/f"},
+	}
+}
+
+// seedDatabase writes recs into a fresh database, closes it as scan
+// does, out of WAL mode, and returns its path.
+func seedDatabase(t *testing.T, recs []scanRec) string {
+	t.Helper()
+
+	path := testDBPath(t)
+
+	db, err := openScanDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = applyChanges(t.Context(), db, recs, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	closeScanDatabase(t.Context(), db, path)
+
+	return path
+}
+
+// dupeGroup is one duplicate group as report reads it: the size, and
+// the paths in report order, first path first.
+type dupeGroup struct {
+	size  int64
+	paths []string
+}
+
+// dupeGroups returns the duplicate groups report reads from db, in
+// report order, from the rows it writes: a group's rows come together,
+// each naming the group's first path.
+func dupeGroups(t *testing.T, db *sql.DB) []dupeGroup {
+	t.Helper()
+
+	var out bytes.Buffer
+
+	_, err := readReport(t.Context(), db, "", &out, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var groups []dupeGroup
+
+	rows := strings.Split(strings.TrimSuffix(out.String(), "\n"), "\n")
+	for _, row := range rows[1:] { // after the header
+		fields := strings.Split(row, "\t")
+		if len(fields) != 3 {
+			t.Fatalf("row %q, want first, dupe and size", row)
+		}
+
+		size, err := strconv.ParseInt(fields[2], 10, 64)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		if len(groups) == 0 || groups[len(groups)-1].paths[0] != fields[0] {
+			groups = append(groups,
+				dupeGroup{size: size, paths: []string{fields[0]}})
+		}
+
+		g := &groups[len(groups)-1]
+		g.paths = append(g.paths, fields[1])
+	}
+
+	return groups
+}
+
+// dupeGroupsOf writes recs into a fresh database and returns the
+// duplicate groups report reads from it.
+func dupeGroupsOf(t *testing.T, recs []scanRec) []dupeGroup {
+	t.Helper()
+
+	db := openTestDB(t)
+
+	err := applyChanges(t.Context(), db, recs, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return dupeGroups(t, db)
+}
+
+func TestRunReportEscapesPaths(t *testing.T) {
+	t.Setenv(databaseEnv, seedDatabase(t, awkwardPairRecs()))
+
+	var stdout, stderr bytes.Buffer
+
+	code := run([]string{cmdReport}, &stdout, &stderr)
+	if code != exitOK {
+		t.Fatalf("run(report) = %d, want %d; stderr: %s",
+			code, exitOK, stderr.String())
+	}
+
+	want := "first\tdupe\tsize\n" +
+		`/d/\tone\ntwo\rthree\\four/f` + "\t/d/A/f\t5\n"
+	if got := stdout.String(); got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+}
+
+func TestReportStdoutFailsWhileReading(t *testing.T) {
+	t.Parallel()
+
+	// Every two records are a duplicate pair of a size of their own, and
+	// a pair's row is written once a smaller size is read. Each row
+	// holds two paths longer than dir, so the rows come to more than
+	// twice the stdout buffer, and stdout fails while records are still
+	// being read, not once every record is.
+	dir := "/" + strings.Repeat("d", 4096)
+
+	recs := make([]scanRec, 2*ioBufSize/len(dir))
+	for i := range recs {
+		recs[i] = scanRec{
+			size: int64(i/2) + 1, head: testHash("h"), tail: testHash("t"),
+			content: testHash("c"), path: fmt.Sprintf("%s/%d", dir, i),
+		}
+	}
+
+	db := openTestDB(t)
+
+	err := applyChanges(t.Context(), db, recs, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Counts the records read, and draws nothing.
+	prog := &progress{now: time.Now}
+
+	_, err = readReport(t.Context(), db, "", failingWriter{}, prog)
+	if !errors.Is(err, errWriteFailed) ||
+		!strings.HasPrefix(err.Error(), "write stdout: ") {
+		t.Errorf("error = %v, want write stdout: %v", err, errWriteFailed)
+	}
+
+	if prog.count >= int64(len(recs)) {
+		t.Errorf("stdout failed after all %d records were read, want it "+
+			"to stop the read", prog.count)
+	}
+}
+
+// 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, " +
+	"remain unknown"
+
+// smokeReport is report's stdout for the smoke-test records.
+const smokeReport = "first\tdupe\tsize\n" +
+	"/d/t1/f1\t/d/t2/f1\t3000\n" +
+	"/d/t1/f1\t/d/t3/f1\t3000\n" +
+	"/d/t1/sub/f2\t/d/t2/sub/f2\t100\n" +
+	"/d/t1/sub/f2\t/d/t3/sub/f2renamed\t100\n"
+
+// TestRunReportProgressNamesEachPhase runs report on the smoke-test
+// records with stderr not a terminal, and checks every line it prints
+// there. After the line naming the database, each phase prints a line
+// naming it with its place among the two as it starts and another as
+// it ends; read counts the 6 records before it reads them. The summary
+// comes last, and stdout holds the report alone.
+func TestRunReportProgressNamesEachPhase(t *testing.T) {
+	path := seedDatabase(t, smokeTreeRecs())
+	t.Setenv(databaseEnv, path)
+
+	stderr := captureStderr(t)
+
+	var stdout bytes.Buffer
+
+	code := run([]string{cmdReport}, &stdout, os.Stderr)
+	if code != exitOK {
+		t.Fatalf("run(report) = %d, want %d; stderr: %s",
+			code, exitOK, stderr())
+	}
+
+	if got := stdout.String(); got != smokeReport {
+		t.Errorf("stdout = %q, want %q", got, smokeReport)
+	}
+
+	// How each line starts; the rate at the end of a phase varies.
+	want := []string{
+		"report: database " + path + " (from " + databaseEnv + ")",
+		reportOpenLine,
+		reportOpenLine,
+		"[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",
+	}
+
+	lines := strings.Split(strings.TrimSuffix(stderr(), "\n"), "\n")
+	if len(lines) != len(want) {
+		t.Fatalf("stderr lines = %q, want %d lines starting %q",
+			lines, len(want), want)
+	}
+
+	for i := range want {
+		if !strings.HasPrefix(lines[i], want[i]) {
+			t.Errorf("stderr line %d = %q, want it to start %q",
+				i+1, lines[i], want[i])
+		}
+	}
+}
+
+// TestReadReportOnTerminal writes the smoke-test report to the terminal
+// its read phase's display is drawn on, as a plain "sfdupes report"
+// does: the terminal must show the header and every row whole, each on
+// a line of its own.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestReadReportOnTerminal(t *testing.T) {
+	stderr := captureStderr(t)
+	db := openTestDB(t)
+
+	err := applyChanges(t.Context(), db, smokeTreeRecs(), nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// No timed draws: the display is drawn as it starts and as it ends.
+	p := startProgress(progressParams{
+		label: reportPhase("read"), unit: "records", total: -1,
+		waitingFor: countingRecords,
+	}, terminalWidth, time.Hour, time.Now)
+
+	_, err = readReport(t.Context(), db, "", os.Stderr, p)
+
+	p.finish()
+
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// A terminal shows each line as the text after its last carriage
+	// return.
+	var shown []string
+
+	for line := range strings.SplitSeq(stderr(), "\n") {
+		shown = append(shown, line[strings.LastIndex(line, "\r")+1:])
+	}
+
+	want := strings.Split(strings.TrimSuffix(smokeReport, "\n"), "\n")
+	if len(shown) < len(want) || !slices.Equal(shown[:len(want)], want) {
+		t.Errorf("terminal shows lines %q, want %q first", shown, want)
+	}
+}
+
+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"},
+	)
+
+	reversed := slices.Clone(recs)
+	slices.Reverse(reversed)
+
+	for _, name := range []string{cmdReport, cmdTrees} {
+		t.Run(name, func(t *testing.T) {
+			t.Setenv(databaseEnv, seedDatabase(t, recs))
+
+			forward := runStdout(t, name)
+
+			t.Setenv(databaseEnv, seedDatabase(t, reversed))
+
+			backward := runStdout(t, name)
+
+			if strings.Count(forward, "\n") < 3 {
+				t.Errorf("stdout = %q, want at least two rows", forward)
+			}
+
+			if forward != backward {
+				t.Errorf("stdout depends on insertion order: %q vs %q",
+					forward, backward)
+			}
+		})
+	}
+}
+
+// runStdout runs the subcommand name and returns its stdout, failing
+// the test unless it succeeds.
+func runStdout(t *testing.T, name string) string {
+	t.Helper()
+
+	var stdout, stderr bytes.Buffer
+
+	code := run([]string{name}, &stdout, &stderr)
+	if code != exitOK {
+		t.Fatalf("run(%s) = %d, want %d; stderr: %s",
+			name, code, exitOK, stderr.String())
+	}
+
+	return stdout.String()
+}
+
+func TestEscapePath(t *testing.T) {
+	t.Parallel()
+
+	cases := map[string]string{
+		"/srv/plain":    "/srv/plain",
+		"/a\tb":         `/a\tb`,
+		"/a\nb":         `/a\nb`,
+		"/a\rb":         `/a\rb`,
+		`/a\b`:          `/a\\b`,
+		`/a\tb`:         `/a\\tb`,
+		"/not-utf8\xff": "/not-utf8\xff",
+	}
+	for in, want := range cases {
+		if got := escapePath(in); got != want {
+			t.Errorf("escapePath(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+// TestWarnfEscapes checks that a warning naming a path that holds a
+// newline is still one line.
+//
+//nolint:paralleltest // replaces the process-wide os.Stderr
+func TestWarnfEscapes(t *testing.T) {
+	f, err := os.Create(filepath.Join(t.TempDir(), "stderr"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	saved := os.Stderr
+	os.Stderr = f
+
+	t.Cleanup(func() {
+		os.Stderr = saved
+
+		_ = f.Close()
+	})
+
+	(&progress{}).warnf("stat %s: %s", "/d/a\nb", "gone")
+
+	_, err = f.Seek(0, io.SeekStart)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := io.ReadAll(f)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	want := `stat /d/a\nb: gone` + "\n"
+	if string(got) != want {
+		t.Errorf("warning = %q, want %q", got, want)
+	}
+}
+
+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: 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: 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"},
+	}
+
+	groups := dupeGroupsOf(t, recs)
+	if len(groups) != 2 {
+		t.Fatalf("len(groups) = %d, want 2", len(groups))
+	}
+
+	if groups[0].size != 4000 ||
+		!slices.Equal(groups[0].paths, []string{"/big/1", "/big/2"}) {
+		t.Errorf("groups[0] = %+v, want size 4000, paths /big/1 /big/2",
+			groups[0])
+	}
+
+	if groups[1].size != 100 ||
+		!slices.Equal(groups[1].paths, []string{"/z/a", "/z/b", "/z/c"}) {
+		t.Errorf("groups[1] = %+v, want size 100, paths /z/a /z/b /z/c",
+			groups[1])
+	}
+}
+
+func TestDupeGroupsContentSeparates(t *testing.T) {
+	t.Parallel()
+
+	// 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: 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)
+	if len(groups) != 1 {
+		t.Fatalf("len(groups) = %d, want 1 (only the matching content)",
+			len(groups))
+	}
+
+	if !slices.Equal(groups[0].paths, []string{"/a", "/c"}) {
+		t.Errorf("group paths = %q, want /a /c", groups[0].paths)
+	}
+}
+
+func TestDupeGroupsMtimeExcluded(t *testing.T) {
+	t.Parallel()
+
+	// 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: tl,
+			content: c, path: "/m/1",
+		},
+		{
+			size: 9, mtime: time.Unix(200, 0), head: h, tail: tl,
+			content: c, path: "/m/2",
+		},
+	}
+
+	groups := dupeGroupsOf(t, recs)
+	if len(groups) != 1 {
+		t.Fatalf("len(groups) = %d, want 1", len(groups))
+	}
+}
+
+func TestDupeGroupsTieBreak(t *testing.T) {
+	t.Parallel()
+
+	// 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"},
+	}
+
+	groups := dupeGroupsOf(t, recs)
+	if len(groups) != 2 {
+		t.Fatalf("len(groups) = %d, want 2", len(groups))
+	}
+
+	// Equal sizes: ordered by first path ascending.
+	if groups[0].paths[0] != "/alpha/1" || groups[1].paths[0] != "/beta/1" {
+		t.Fatalf("tie-break order wrong: %q then %q",
+			groups[0].paths[0], groups[1].paths[0])
+	}
+}
+
+func TestDupeGroupsOrderedByFirstPath(t *testing.T) {
+	t.Parallel()
+
+	// report reads the groups of size 50 in signature order, here /a,
+	// /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"},
+	}
+
+	groups := dupeGroupsOf(t, recs)
+
+	got := make([]string, 0, len(groups))
+	for _, g := range groups {
+		got = append(got, g.paths[0])
+	}
+
+	want := []string{"/a/1", "/k/1", "/z/1", "/0/1"}
+	if !slices.Equal(got, want) {
+		t.Errorf("groups' first paths = %q, want %q", got, want)
+	}
+}
+
+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"},
+	}
+
+	forward := dupeGroupsOf(t, recs)
+
+	reversed := slices.Clone(recs)
+	slices.Reverse(reversed)
+
+	backward := dupeGroupsOf(t, reversed)
+	if !slices.EqualFunc(forward, backward, func(a, b dupeGroup) bool {
+		return a.size == b.size && slices.Equal(a.paths, b.paths)
+	}) {
+		t.Fatalf("output depends on record order: %+v vs %+v",
+			forward, backward)
+	}
+}
+
+func TestHumanBytes(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		n    int64
+		want string
+	}{
+		{0, "0 B"},
+		{1, "1 B"},
+		{1023, "1023 B"},
+		{1024, "1.0 KiB"},
+		{1536, "1.5 KiB"},
+		{1 << 20, "1.0 MiB"},
+		{5 << 30, "5.0 GiB"},
+		{1 << 40, "1.0 TiB"},
+		{1 << 50, "1.0 PiB"},
+		{1 << 60, "1.0 EiB"},
+	}
+	for _, c := range cases {
+		if got := humanBytes(c.n); got != c.want {
+			t.Errorf("humanBytes(%d) = %q, want %q", c.n, got, c.want)
+		}
+	}
+}

internal/sfdupes/scan_dev_darwin.go

@@ -0,0 +1,14 @@
+//go:build darwin
+
+package sfdupes
+
+import "syscall"
+
+// statDev returns the filesystem device ID of st as uint64. Device IDs
+// are opaque; the conversion only needs to be consistent so equality
+// comparisons work, not numerically meaningful.
+//
+//nolint:gosec // int32 device IDs convert consistently; only equality matters
+func statDev(st *syscall.Stat_t) uint64 {
+	return uint64(st.Dev)
+}

internal/sfdupes/scan_dev_other.go

@@ -0,0 +1,10 @@
+//go:build !darwin
+
+package sfdupes
+
+import "syscall"
+
+// statDev returns the filesystem device ID of st.
+func statDev(st *syscall.Stat_t) uint64 {
+	return st.Dev
+}

internal/sfdupes/trees.go

@@ -0,0 +1,392 @@
+package sfdupes
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"fmt"
+	"io"
+	"os"
+	"slices"
+	"strconv"
+	"strings"
+)
+
+// treeNode is one directory reconstructed from the record paths.
+type treeNode struct {
+	path   string
+	parent *treeNode
+	// entries holds the serialized child entries until the digest is
+	// computed from them, and is then dropped.
+	entries   []string
+	digest    [sha256.Size]byte
+	fileCount int64
+	totalSize int64
+	// diskSize is the bytes the directory's files take on disk. Two
+	// copies of one tree have the same totalSize, but their diskSize
+	// can differ.
+	diskSize int64
+}
+
+// treesPhase names one phase of trees with its place among all of them,
+// as "[2/4] read", for the phase's progress display. The list here is
+// the one place the phases are counted.
+func treesPhase(name string) string {
+	return phaseLabel([]string{openPhase, "read", "group", "write"}, name)
+}
+
+// runTrees implements the trees subcommand: it reads every record from
+// the database in path order, reconstructs the directory hierarchy from
+// the record paths, computes a Merkle-style digest per directory, and
+// prints maximal duplicate-tree groups as TSV on stdout. It never
+// touches the scanned filesystem; its only I/O is the database, stdout,
+// and stderr. It names the database on stderr before it opens it. Any
+// database problem, including a missing database, is fatal.
+//
+// The work runs in four phases, each under a progress display of its
+// own on stderr: open (open the database), read (read the number of
+// records from the totals table, then read the records into the
+// hierarchy), group (group the directories by digest) and write (write
+// the groups to stdout). Each display ends before the next phase
+// starts, and before an error is returned to be printed.
+func runTrees(ctx context.Context, stdout io.Writer) error {
+	dbPath, source, err := databasePath()
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(os.Stderr, "trees: database %s (%s)\n",
+		escapePath(dbPath), source)
+
+	// Opening can wait on a busy database for as long as the busy
+	// timeout.
+	prog := newProgress(progressParams{
+		label: treesPhase(openPhase), total: -1,
+		waitingFor: openingDatabase,
+	})
+	db, err := openReportDatabase(ctx, dbPath)
+
+	prog.finish()
+
+	if err != nil {
+		return err
+	}
+
+	defer func() { _ = db.Close() }()
+
+	prog = newProgress(progressParams{
+		label: treesPhase("read"), unit: "records", total: -1,
+		waitingFor: countingRecords, stalledOn: "db",
+	})
+	records, super, allDirs, err := readTree(ctx, db, prog)
+
+	prog.finish()
+
+	if err != nil {
+		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)), stalledOn: "cpu",
+	})
+	dupes := collectTreeGroups(allDirs, super, prog)
+
+	prog.finish()
+
+	prog = newProgress(progressParams{
+		label: treesPhase("write"), unit: "groups", total: int64(len(dupes)),
+		stalledOn: "out",
+	})
+	dupeTrees, reclaimable, err := writeTreeGroups(stdout, dupes, prog)
+
+	prog.finish()
+
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintf(os.Stderr,
+		"trees: %d records read, %d duplicate tree groups, %d dupe trees, "+
+			"%s reclaimable\n",
+		records, len(dupes), dupeTrees, humanBytes(reclaimable))
+
+	return nil
+}
+
+// readTree gives prog the number of records in db as its total, then
+// reads every record in path order into the directory hierarchy,
+// counting each on prog. It returns the number of records read, the
+// super-root and every directory.
+func readTree(ctx context.Context, db *sql.DB,
+	prog *progress,
+) (int, *treeNode, []*treeNode, error) {
+	records := 0
+	tree := newTreeBuilder()
+
+	err := loadFileRows(ctx, db, prog.setTotal, func(r scanRec) {
+		records++
+
+		prog.increment()
+		tree.add(r)
+	})
+	if err != nil {
+		return 0, nil, nil, err
+	}
+
+	super, allDirs := tree.finish()
+
+	return records, super, allDirs, nil
+}
+
+// writeTreeGroups writes dupes to stdout as TSV, a header line and then
+// a row for every member of each group but its first, counting each
+// group on prog once its rows are written. The disk_size column is the
+// dupe's own. stdout may be the terminal prog is drawn on, so the lines
+// go through prog's writer. It returns the number of rows (dupe trees)
+// and the bytes they could reclaim.
+func writeTreeGroups(stdout io.Writer, dupes [][]*treeNode,
+	prog *progress,
+) (int, int64, error) {
+	out := prog.writer(stdout)
+
+	_, err := fmt.Fprintln(out, "first\tdupe\tfiles\tsize\tdisk_size")
+	if err != nil {
+		return 0, 0, fmt.Errorf("write stdout: %w", err)
+	}
+
+	dupeTrees := 0
+
+	var reclaimable int64
+
+	for _, g := range dupes {
+		first := g[0]
+		for _, n := range g[1:] {
+			_, err = fmt.Fprintf(out, "%s\t%s\t%d\t%d\t%d\n",
+				escapePath(first.path), escapePath(n.path),
+				first.fileCount, first.totalSize, n.diskSize)
+			if err != nil {
+				return 0, 0, fmt.Errorf("write stdout: %w", err)
+			}
+
+			dupeTrees++
+			reclaimable += first.totalSize
+		}
+
+		prog.increment()
+	}
+
+	err = out.Flush()
+	if err != nil {
+		return 0, 0, fmt.Errorf("write stdout: %w", err)
+	}
+
+	return dupeTrees, reclaimable, nil
+}
+
+// treeBuilder reconstructs the directory hierarchy from records added
+// in path order, under a synthetic super-root. Paths are split on "/";
+// for absolute paths the first component is empty, which becomes the
+// top-level directory with path "/". In path order all the paths under
+// one directory come together, so a directory is complete once a path
+// outside it is added: its digest is computed then and its entries are
+// dropped. Only the directories holding the latest path keep entries.
+type treeBuilder struct {
+	super *treeNode
+	// open lists the directories holding the latest path, outermost
+	// first, starting with the super-root; names[i] is open[i]'s name.
+	open  []*treeNode
+	names []string
+	// dirs lists every completed directory.
+	dirs []*treeNode
+}
+
+func newTreeBuilder() *treeBuilder {
+	super := &treeNode{}
+
+	return &treeBuilder{
+		super: super,
+		open:  []*treeNode{super},
+		names: []string{""},
+	}
+}
+
+// add adds one record. Each record must come after the previous one in
+// path order (byte order); otherwise a completed directory would be
+// started again as a second directory with the same path.
+func (b *treeBuilder) add(r scanRec) {
+	comps := strings.Split(r.path, "/")
+	dirNames, name := comps[:len(comps)-1], comps[len(comps)-1]
+
+	// Keep the open directories that hold this path; complete the rest.
+	depth := 1
+	for depth < len(b.open) && depth <= len(dirNames) &&
+		b.names[depth] == dirNames[depth-1] {
+		depth++
+	}
+
+	b.closeTo(depth)
+
+	for _, c := range dirNames[depth-1:] {
+		b.openDir(c)
+	}
+
+	dir := b.open[len(b.open)-1]
+	dir.entries = append(dir.entries, fileEntry(name, r))
+	dir.fileCount++
+	dir.totalSize += r.size
+	dir.diskSize += r.diskSize
+}
+
+// openDir starts the directory called name inside the innermost open
+// one.
+func (b *treeBuilder) openDir(name string) {
+	parent := b.open[len(b.open)-1]
+	path := parent.path + "/" + name
+
+	// The root directory's path is "/", not empty, and its children's
+	// paths start with one slash, not two.
+	switch {
+	case parent == b.super && name == "":
+		path = "/"
+	case parent == b.super:
+		path = name
+	case parent.path == "/":
+		path = "/" + name
+	}
+
+	b.open = append(b.open, &treeNode{path: path, parent: parent})
+	b.names = append(b.names, name)
+}
+
+// closeTo completes the open directories after the first n, innermost
+// first: each one's digest is computed and entered in its parent along
+// with its totals.
+func (b *treeBuilder) closeTo(n int) {
+	for len(b.open) > n {
+		last := len(b.open) - 1
+		dir, name := b.open[last], b.names[last]
+		b.open, b.names = b.open[:last], b.names[:last]
+
+		dir.computeDigest()
+
+		dir.parent.entries = append(dir.parent.entries,
+			"d\x00"+name+"\x00"+string(dir.digest[:]))
+		dir.parent.fileCount += dir.fileCount
+		dir.parent.totalSize += dir.totalSize
+		dir.parent.diskSize += dir.diskSize
+		b.dirs = append(b.dirs, dir)
+	}
+}
+
+// finish completes every open directory and returns the super-root and
+// every directory.
+func (b *treeBuilder) finish() (*treeNode, []*treeNode) {
+	b.closeTo(1)
+
+	return b.super, b.dirs
+}
+
+// fileEntry serializes a file child for its directory's digest: its
+// name and its signature (size, head, tail, content); mtime is
+// excluded.
+func fileEntry(name string, r scanRec) string {
+	return "f\x00" + name + "\x00" + strconv.FormatInt(r.size, 10) +
+		"\x00" + string(r.head[:]) + "\x00" + string(r.tail[:]) +
+		"\x00" + string(r.content[:])
+}
+
+// collectTreeGroups groups directories by digest, counting each one on
+// prog as it is grouped, and returns every maximal group with two or
+// more members, each group's members sorted by path, groups ordered by
+// tree size descending then by first path ascending.
+func collectTreeGroups(allDirs []*treeNode, super *treeNode,
+	prog *progress,
+) [][]*treeNode {
+	groups := make(map[[sha256.Size]byte][]*treeNode)
+	for _, d := range allDirs {
+		groups[d.digest] = append(groups[d.digest], d)
+
+		prog.increment()
+	}
+
+	var dupes [][]*treeNode
+
+	for _, g := range groups {
+		if len(g) < minGroupSize || suppressed(g, super) {
+			continue
+		}
+
+		slices.SortFunc(g, func(a, b *treeNode) int {
+			return strings.Compare(a.path, b.path)
+		})
+		dupes = append(dupes, g)
+	}
+
+	// Biggest reclaimable space first; ties broken by first path.
+	slices.SortFunc(dupes, func(a, b []*treeNode) int {
+		if a[0].totalSize != b[0].totalSize {
+			if a[0].totalSize > b[0].totalSize {
+				return -1
+			}
+
+			return 1
+		}
+
+		return strings.Compare(a[0].path, b[0].path)
+	})
+
+	return dupes
+}
+
+// computeDigest sets n's digest and drops its entries. A directory's
+// 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 "/",
+// and every hash and digest is 32 bytes, so NUL delimiters are
+// unambiguous.
+func (n *treeNode) computeDigest() {
+	slices.Sort(n.entries)
+
+	h := sha256.New()
+	for _, e := range n.entries {
+		h.Write([]byte(e))
+		h.Write([]byte{0})
+	}
+
+	copy(n.digest[:], h.Sum(nil))
+	n.entries = nil
+}
+
+// suppressed reports whether a duplicate-tree group is non-maximal: its
+// members' parents are pairwise distinct real directories that all
+// share a single digest, so the group is wholly implied by its parents'
+// (or a further ancestor's) group. Groups containing siblings (shared
+// parent) or members whose parents differ are always reported.
+func suppressed(g []*treeNode, super *treeNode) bool {
+	seen := make(map[*treeNode]bool, len(g))
+
+	var parentDigest [sha256.Size]byte
+
+	for i, n := range g {
+		p := n.parent
+		if p == nil || p == super {
+			return false
+		}
+
+		if seen[p] {
+			return false // siblings: not implied by any parent group
+		}
+
+		seen[p] = true
+		if i == 0 {
+			parentDigest = p.digest
+		} else if p.digest != parentDigest {
+			return false
+		}
+	}
+
+	return true
+}

internal/sfdupes/trees_test.go

@@ -0,0 +1,459 @@
+package sfdupes //nolint:testpackage // checks the unexported treeNode results
+
+import (
+	"bytes"
+	"database/sql"
+	"os"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+)
+
+// 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, " +
+	"remain unknown"
+
+// smokeTreeRecs mirrors the tree of the test under README "Definition
+// of done": /d/t1 and /d/t2 are identical, /d/t3 differs from them only
+// by one filename. Each file takes one 4 KiB block on disk.
+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, diskSize: 4096, head: f1Head, tail: f1Tail,
+			content: f1Content, path: "/d/t1/f1"},
+		{size: 100, diskSize: 4096, head: f2Head, tail: f2Tail,
+			content: f2Content, path: "/d/t1/sub/f2"},
+		{size: 3000, diskSize: 4096, head: f1Head, tail: f1Tail,
+			content: f1Content, path: "/d/t2/f1"},
+		{size: 100, diskSize: 4096, head: f2Head, tail: f2Tail,
+			content: f2Content, path: "/d/t2/sub/f2"},
+		{size: 3000, diskSize: 4096, head: f1Head, tail: f1Tail,
+			content: f1Content, path: "/d/t3/f1"},
+		{size: 100, diskSize: 4096, head: f2Head, tail: f2Tail,
+			content: f2Content, path: "/d/t3/sub/f2renamed"},
+	}
+}
+
+// dbTree builds the directory hierarchy from the records in db the way
+// trees does, and returns the super-root and every directory.
+func dbTree(t *testing.T, db *sql.DB) (*treeNode, []*treeNode) {
+	t.Helper()
+
+	tree := newTreeBuilder()
+
+	err := loadFileRows(t.Context(), db, func(int64) {}, tree.add)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return tree.finish()
+}
+
+// treeOf writes recs into a fresh database and builds the directory
+// hierarchy from it the way trees does.
+func treeOf(t *testing.T, recs []scanRec) (*treeNode, []*treeNode) {
+	t.Helper()
+
+	db := openTestDB(t)
+
+	err := applyChanges(t.Context(), db, recs, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return dbTree(t, db)
+}
+
+// nodeByPath finds the directory node with the given path.
+func nodeByPath(t *testing.T, dirs []*treeNode, path string) *treeNode {
+	t.Helper()
+
+	for _, d := range dirs {
+		if d.path == path {
+			return d
+		}
+	}
+
+	t.Fatalf("no directory node with path %q", path)
+
+	return nil
+}
+
+// groupPaths flattens tree groups into their member path lists.
+func groupPaths(groups [][]*treeNode) [][]string {
+	out := make([][]string, 0, len(groups))
+	for _, g := range groups {
+		paths := make([]string, 0, len(g))
+		for _, n := range g {
+			paths = append(paths, n.path)
+		}
+
+		out = append(out, paths)
+	}
+
+	return out
+}
+
+func TestTreeCounts(t *testing.T) {
+	t.Parallel()
+
+	_, dirs := treeOf(t, smokeTreeRecs())
+
+	d := nodeByPath(t, dirs, "/d")
+	if d.fileCount != 6 || d.totalSize != 9300 {
+		t.Errorf("/d: fileCount %d size %d, want 6 9300",
+			d.fileCount, d.totalSize)
+	}
+
+	t1 := nodeByPath(t, dirs, "/d/t1")
+	if t1.fileCount != 2 || t1.totalSize != 3100 {
+		t.Errorf("/d/t1: fileCount %d size %d, want 2 3100",
+			t1.fileCount, t1.totalSize)
+	}
+
+	sub := nodeByPath(t, dirs, "/d/t1/sub")
+	if sub.fileCount != 1 || sub.totalSize != 100 {
+		t.Errorf("/d/t1/sub: fileCount %d size %d, want 1 100",
+			sub.fileCount, sub.totalSize)
+	}
+}
+
+func TestTreeRootPath(t *testing.T) {
+	t.Parallel()
+
+	// The root directory's path is "/", never empty, and its
+	// children's paths start with a single slash.
+	_, dirs := treeOf(t, []scanRec{{path: "/f"}, {path: "/srv/g"}})
+
+	got := make([]string, 0, len(dirs))
+	for _, d := range dirs {
+		got = append(got, d.path)
+	}
+
+	slices.Sort(got)
+
+	want := []string{"/", "/srv"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("directory paths = %q, want %q", got, want)
+	}
+}
+
+func TestTreeNamesSortingBeforeSlash(t *testing.T) {
+	t.Parallel()
+
+	// In path order "/a/b-x/f" and "/a/b.txt" come between the file
+	// "/a/b" and "/a/b/f", because "-" and "." sort before "/". Each
+	// directory must still be built once, whole, so /a matches /c.
+	recs := make([]scanRec, 0, 8)
+
+	for _, top := range []string{"/a", "/c"} {
+		for _, p := range []string{"/b", "/b-x/f", "/b.txt", "/b/f"} {
+			content := testHash("c")
+			if p == "/b-x/f" {
+				content = testHash("other")
+			}
+
+			recs = append(recs, scanRec{
+				size: 1, head: testHash("h"), tail: testHash("t"),
+				content: content, path: top + p,
+			})
+		}
+	}
+
+	super, dirs := treeOf(t, recs)
+
+	got := make([]string, 0, len(dirs))
+	for _, d := range dirs {
+		got = append(got, d.path)
+	}
+
+	slices.Sort(got)
+
+	want := []string{"/", "/a", "/a/b", "/a/b-x", "/c", "/c/b", "/c/b-x"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("directory paths = %q, want %q", got, want)
+	}
+
+	groups := collectTreeGroups(dirs, super, nil)
+
+	gotGroups := groupPaths(groups)
+	wantGroups := [][]string{{"/a", "/c"}}
+
+	if !slices.EqualFunc(gotGroups, wantGroups, slices.Equal) {
+		t.Fatalf("groups = %v, want %v", gotGroups, wantGroups)
+	}
+
+	if groups[0][0].fileCount != 4 || groups[0][0].totalSize != 4 {
+		t.Errorf("group totals: %d files %d bytes, want 4 4",
+			groups[0][0].fileCount, groups[0][0].totalSize)
+	}
+}
+
+func TestRunTreesEscapesPaths(t *testing.T) {
+	t.Setenv(databaseEnv, seedDatabase(t, awkwardPairRecs()))
+
+	var stdout, stderr bytes.Buffer
+
+	code := run([]string{cmdTrees}, &stdout, &stderr)
+	if code != exitOK {
+		t.Fatalf("run(trees) = %d, want %d; stderr: %s",
+			code, exitOK, stderr.String())
+	}
+
+	want := "first\tdupe\tfiles\tsize\tdisk_size\n" +
+		`/d/\tone\ntwo\rthree\\four` + "\t/d/A\t1\t5\t4096\n"
+	if got := stdout.String(); got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+}
+
+// TestRunTreesDiskSize runs trees on two copies of a tree whose files
+// take different space on disk. The row's disk_size is the sum over the
+// dupe copy's files, those in its subdirectory included.
+func TestRunTreesDiskSize(t *testing.T) {
+	f, g := testHash("f"), testHash("g")
+	recs := []scanRec{
+		{size: 10, diskSize: 4096, head: f, tail: f, content: f, path: "/a/f"},
+		{size: 20, diskSize: 4096, head: g, tail: g, content: g, path: "/a/sub/g"},
+		{size: 10, diskSize: 512, head: f, tail: f, content: f, path: "/b/f"},
+		{size: 20, diskSize: 1024, head: g, tail: g, content: g, path: "/b/sub/g"},
+	}
+
+	t.Setenv(databaseEnv, seedDatabase(t, recs))
+
+	want := "first\tdupe\tfiles\tsize\tdisk_size\n/a\t/b\t2\t30\t1536\n"
+	if got := runStdout(t, cmdTrees); got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+}
+
+// TestRunTreesProgressNamesEachPhase runs trees on the smoke-test
+// records with stderr not a terminal, and checks every line it prints
+// there. After the line naming the database, each phase prints a line
+// naming it with its place among the four as it starts and another as
+// it ends. read counts the 6 records before it reads them, group counts
+// the 8 directories, and write the 1 group. The summary comes last, and
+// stdout holds the report alone.
+func TestRunTreesProgressNamesEachPhase(t *testing.T) {
+	path := seedDatabase(t, smokeTreeRecs())
+	t.Setenv(databaseEnv, path)
+
+	stderr := captureStderr(t)
+
+	var stdout bytes.Buffer
+
+	code := run([]string{cmdTrees}, &stdout, os.Stderr)
+	if code != exitOK {
+		t.Fatalf("run(trees) = %d, want %d; stderr: %s",
+			code, exitOK, stderr())
+	}
+
+	report := "first\tdupe\tfiles\tsize\tdisk_size\n" +
+		"/d/t1\t/d/t2\t2\t3100\t8192\n"
+	if got := stdout.String(); got != report {
+		t.Errorf("stdout = %q, want %q", got, report)
+	}
+
+	// How each line starts; the rate at the end of a phase varies.
+	want := []string{
+		"trees: database " + path + " (from " + databaseEnv + ")",
+		treesOpenLine,
+		treesOpenLine,
+		"[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, remain unknown",
+		"[3/4] group: [8/8] 100%, ",
+		"[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, ",
+	}
+
+	lines := strings.Split(strings.TrimSuffix(stderr(), "\n"), "\n")
+	if len(lines) != len(want) {
+		t.Fatalf("stderr lines = %q, want %d lines starting %q",
+			lines, len(want), want)
+	}
+
+	for i := range want {
+		if !strings.HasPrefix(lines[i], want[i]) {
+			t.Errorf("stderr line %d = %q, want it to start %q",
+				i+1, lines[i], want[i])
+		}
+	}
+}
+
+// TestWriteTreeGroupsOnTerminal writes the smoke-test report to the
+// terminal its write phase's display is drawn on, as a plain "sfdupes
+// trees" does: the terminal must show the header and the row whole,
+// each on a line of its own.
+//
+//nolint:paralleltest // captureStderr replaces the process-wide os.Stderr
+func TestWriteTreeGroupsOnTerminal(t *testing.T) {
+	stderr := captureStderr(t)
+	super, dirs := treeOf(t, smokeTreeRecs())
+	dupes := collectTreeGroups(dirs, super, nil)
+
+	// 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, time.Now)
+
+	_, _, err := writeTreeGroups(os.Stderr, dupes, p)
+
+	p.finish()
+
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// A terminal shows each line as the text after its last carriage
+	// return.
+	var shown []string
+
+	for line := range strings.SplitSeq(stderr(), "\n") {
+		shown = append(shown, line[strings.LastIndex(line, "\r")+1:])
+	}
+
+	want := []string{
+		"first\tdupe\tfiles\tsize\tdisk_size", "/d/t1\t/d/t2\t2\t3100\t8192",
+	}
+	if len(shown) < len(want) || !slices.Equal(shown[:len(want)], want) {
+		t.Errorf("terminal shows lines %q, want %q first", shown, want)
+	}
+}
+
+func TestTreeDigests(t *testing.T) {
+	t.Parallel()
+
+	_, dirs := treeOf(t, smokeTreeRecs())
+
+	t1 := nodeByPath(t, dirs, "/d/t1")
+	t2 := nodeByPath(t, dirs, "/d/t2")
+	t3 := nodeByPath(t, dirs, "/d/t3")
+
+	if t1.digest != t2.digest {
+		t.Error("identical trees /d/t1 and /d/t2 have different digests")
+	}
+
+	// t3 differs only in a filename; names are part of the digest.
+	if t1.digest == t3.digest {
+		t.Error("/d/t3 digest equals /d/t1 despite a renamed file")
+	}
+
+	sub1 := nodeByPath(t, dirs, "/d/t1/sub")
+	sub3 := nodeByPath(t, dirs, "/d/t3/sub")
+
+	if sub1.digest == sub3.digest {
+		t.Error("subdirs with differently-named files share a digest")
+	}
+}
+
+func TestTreeDigestContentSensitivity(t *testing.T) {
+	t.Parallel()
+
+	same, c := testHash("same"), testHash("c")
+	recs := []scanRec{
+		{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)
+
+	a := nodeByPath(t, dirs, "/r/a")
+	b := nodeByPath(t, dirs, "/r/b")
+
+	if a.digest == b.digest {
+		t.Error("trees with different file content share a digest")
+	}
+}
+
+func TestCollectTreeGroupsMaximal(t *testing.T) {
+	t.Parallel()
+
+	super, dirs := treeOf(t, smokeTreeRecs())
+
+	groups := collectTreeGroups(dirs, super, nil)
+
+	want := [][]string{{"/d/t1", "/d/t2"}}
+	if got := groupPaths(groups); !slices.EqualFunc(got, want,
+		slices.Equal) {
+		t.Fatalf("groups = %v, want %v", got, want)
+	}
+
+	// The /d/t1/sub vs /d/t2/sub group must be suppressed as implied
+	// by its parents' group; the winning group reports one copy's
+	// recursive totals.
+	if groups[0][0].fileCount != 2 || groups[0][0].totalSize != 3100 {
+		t.Errorf("group totals: %d files %d bytes, want 2 3100",
+			groups[0][0].fileCount, groups[0][0].totalSize)
+	}
+}
+
+func TestCollectTreeGroupsDeterministic(t *testing.T) {
+	t.Parallel()
+
+	recs := smokeTreeRecs()
+
+	super, dirs := treeOf(t, recs)
+
+	forward := groupPaths(collectTreeGroups(dirs, super, nil))
+
+	reversed := slices.Clone(recs)
+	slices.Reverse(reversed)
+
+	superR, dirsR := treeOf(t, reversed)
+
+	backward := groupPaths(collectTreeGroups(dirsR, superR, nil))
+	if !slices.EqualFunc(forward, backward, slices.Equal) {
+		t.Fatalf("output depends on record order: %v vs %v",
+			forward, backward)
+	}
+}
+
+func TestCollectTreeGroupsSiblings(t *testing.T) {
+	t.Parallel()
+
+	// 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: tl, content: c, path: "/p/x1/f"},
+		{size: 10, head: h, tail: tl, content: c, path: "/p/x2/f"},
+	}
+
+	super, dirs := treeOf(t, recs)
+
+	got := groupPaths(collectTreeGroups(dirs, super, nil))
+
+	want := [][]string{{"/p/x1", "/p/x2"}}
+	if !slices.EqualFunc(got, want, slices.Equal) {
+		t.Fatalf("groups = %v, want %v", got, want)
+	}
+}
+
+func TestCollectTreeGroupsDifferingParents(t *testing.T) {
+	t.Parallel()
+
+	// /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: 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)
+
+	got := groupPaths(collectTreeGroups(dirs, super, nil))
+
+	want := [][]string{{"/p/a/x", "/q/b/x"}}
+	if !slices.EqualFunc(got, want, slices.Equal) {
+		t.Fatalf("groups = %v, want %v", got, want)
+	}
+}