Guarantee the database is closed on every fatal exit path (closes #4)

fatalf called os.Exit(1), which does not run deferred functions, so
every defer db.Close() was dead on the fatal path: the SQLite WAL was
left uncheckpointed and the -wal/-shm sidecars were left for the next
process to recover. It also made those paths impossible to exercise
in-process.

fatalf is gone. runScan, runReport, runTrees, loadRecords and
resolveRoots return their errors, so the deferred close always runs,
and the only exit point is run() in main.go.

Mapping errors to exit codes needs care: cobra prints the error and
the command's usage text for anything RunE returns, and main mapped
every Execute() error to exit 2. A runtime failure is not a usage
problem, so the runE adapter silences both for the subcommands and
marks their errors fatalError; run() reports a fatalError as
"sfdupes: ..." on stderr and exits 1, and leaves everything else --
cobra's own argument, flag and unknown-command errors, which cobra has
already reported with its usage text -- on exit 2. The bare
"sfdupes" invocation still prints usage and exits 2.

Exit codes and message text are unchanged: 0 on success even with
per-file warnings, 1 fatal, 2 usage, per README section "Error
handling and exit codes". Everything on stdout is still data only.

main_test.go drives the CLI in-process and covers all three: a fatal
error raised after the database is open (a database with no files
table) closes it and leaves no -wal or -shm behind for scan, report
and trees; a nonexistent PATH operand is fatal, not usage, and prints
no usage text; the usage errors still exit 2; and a scan that skipped
an unreadable file still exits 0.

TODO.md

@@ -29,6 +29,20 @@
 
 # Completed Steps
 
+- guarantee the database is closed on every fatal exit path
+  (2026-08-09, branch `db-close-on-fatal`, closes #4): `fatalf` and
+  its `os.Exit(1)` are gone, so the deferred `db.Close()` — and with
+  it the SQLite WAL checkpoint — now actually runs when a subcommand
+  fails; `runScan`, `runReport`, `runTrees`, `loadRecords` and
+  `resolveRoots` return errors instead. The single exit point is `run`
+  in `main.go`: it maps a `fatalError` (anything a subcommand
+  returned) to exit 1 and cobra's own argument and flag errors to exit
+  2, which keeps a runtime failure from being reported as a usage
+  error or printing the usage text. New `main_test.go` drives the CLI
+  in-process and asserts the exit codes from README §Error handling
+  plus the stdout/stderr split, including that a fatal error raised
+  after the database is open leaves no `-wal`/`-shm` sidecar behind
+  for `scan`, `report` or `trees`
 - update golangci-lint to v2.12.2 with the canonical config
   (2026-08-09, branch `golangci-v2.12.2`, merged as `38a01bd`,
   closes #3): bumped the pinned linter in the `Dockerfile` lint

main.go

@@ -16,20 +16,35 @@
 package main
 
 import (
+	"errors"
 	"fmt"
+	"io"
 	"os"
 	"runtime"
 
 	"github.com/spf13/cobra"
 )
 
-// Exit codes: 0 is success (even with per-file warnings), exitFatal is
-// a fatal error, exitUsage is a usage error.
+// 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"
+)
+
+// 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")
+
 // Version is the build version, injected at link time via -ldflags
 // (see the Makefile); "dev" for a plain go build.
 //
@@ -37,22 +52,64 @@ const (
 var Version = "dev"
 
 func main() {
+	os.Exit(run(os.Args[1:], 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.
+func run(args []string, 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(stderr)
+	root.SetArgs(args)
+
+	err := root.Execute()
+
+	var fatal fatalError
+
+	switch {
+	case err == nil:
+		return exitOK
+	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: cobra has already printed the message and
+		// the usage text.
+		return exitUsage
+	}
+}
+
+// newRootCommand builds the command tree. Everything on stdout is
+// machine-readable data; all human-facing output (help, usage, errors)
+// goes to stderr.
+func newRootCommand(stderr io.Writer) *cobra.Command {
 	root := &cobra.Command{
 		Use:     "sfdupes",
 		Short:   "Find candidate duplicate files by size and head/tail SHA-256",
 		Version: Version,
 		Args:    cobra.NoArgs,
-		Run: func(cmd *cobra.Command, _ []string) {
-			// A missing subcommand prints usage and exits 2.
-			_ = cmd.Usage()
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			// 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
 
-			os.Exit(exitUsage)
+			return errNoSubcommand
 		},
 	}
-	// Everything on stdout is machine-readable data; all human-facing
-	// output (help, usage, errors) goes to stderr.
-	root.SetOut(os.Stderr)
-	root.SetErr(os.Stderr)
+	root.SetOut(stderr)
+	root.SetErr(stderr)
 	root.CompletionOptions.DisableDefaultCmd = true
 
 	var (
@@ -61,12 +118,12 @@ func main() {
 	)
 
 	scanCmd := &cobra.Command{
-		Use:   "scan [--workers N] [-x] PATH...",
+		Use:   cmdScan + " [--workers N] [-x] PATH...",
 		Short: "Walk trees and synchronize the scan database",
 		Args:  cobra.MinimumNArgs(1),
-		Run: func(_ *cobra.Command, args []string) {
-			runScan(args, scanWorkers, scanOneFS)
-		},
+		RunE: runE(func(args []string) error {
+			return runScan(args, scanWorkers, scanOneFS)
+		}),
 	}
 	scanCmd.Flags().IntVar(&scanWorkers, "workers", runtime.NumCPU(),
 		"concurrent workers for the walk and hash phases")
@@ -74,35 +131,55 @@ func main() {
 		"do not cross filesystem boundaries")
 
 	reportCmd := &cobra.Command{
-		Use:   "report",
+		Use:   cmdReport,
 		Short: "Read the scan database and print the file-level duplicates report",
 		Args:  cobra.NoArgs,
-		Run: func(_ *cobra.Command, _ []string) {
-			runReport()
-		},
+		RunE: runE(func(_ []string) error {
+			return runReport()
+		}),
 	}
 
 	treesCmd := &cobra.Command{
-		Use:   "trees",
+		Use:   cmdTrees,
 		Short: "Read the scan database and print the duplicate-tree report",
 		Args:  cobra.NoArgs,
-		Run: func(_ *cobra.Command, _ []string) {
-			runTrees()
-		},
+		RunE: runE(func(_ []string) error {
+			return runTrees()
+		}),
 	}
 
 	root.AddCommand(scanCmd, reportCmd, treesCmd)
 
-	err := root.Execute()
-	if err != nil {
-		// Cobra has already printed the error and usage to stderr;
-		// an invalid subcommand or bad arguments is a usage error.
-		os.Exit(exitUsage)
+	return root
+}
+
+// runE adapts a subcommand implementation 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.
+func runE(fn func(args []string) error) func(*cobra.Command, []string) error {
+	return func(cmd *cobra.Command, args []string) error {
+		cmd.SilenceUsage = true
+		cmd.SilenceErrors = true
+
+		err := fn(args)
+		if err != nil {
+			return fatalError{err: err}
+		}
+
+		return nil
 	}
 }
 
-// fatalf reports a fatal error and exits 1.
-func fatalf(format string, args ...any) {
-	fmt.Fprintf(os.Stderr, "sfdupes: "+format+"\n", args...)
-	os.Exit(exitFatal)
+// 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 }

main_test.go

@@ -0,0 +1,397 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// usageMarker is the first line of cobra's usage text, which a usage
+// error prints and a runtime failure must not.
+const usageMarker = "Usage:"
+
+// walSuffixes are the SQLite sidecar files a WAL-mode database keeps
+// while it is open. A clean close checkpoints the WAL and removes
+// both; finding either afterwards means the database was never closed.
+//
+//nolint:gochecknoglobals // a constant list, immutable by convention
+var walSuffixes = []string{"-wal", "-shm"}
+
+// assertNoSidecars fails when a WAL sidecar is still present beside the
+// database at path.
+func assertNoSidecars(t *testing.T, path string) {
+	t.Helper()
+
+	for _, suffix := range walSuffixes {
+		_, err := os.Stat(path + suffix)
+		if err == nil {
+			t.Errorf("%s%s still present: the database was not closed",
+				path, suffix)
+
+			continue
+		}
+
+		if !errors.Is(err, fs.ErrNotExist) {
+			t.Fatal(err)
+		}
+	}
+}
+
+// captureStdout redirects os.Stdout to a file for the rest of the test
+// and returns a function reading back everything written to it. Only
+// machine-readable data belongs on stdout (README design goal 4), so
+// the tests assert on it directly.
+func captureStdout(t *testing.T) func() string {
+	t.Helper()
+
+	f, err := os.Create(filepath.Join(t.TempDir(), "stdout"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	saved := os.Stdout
+	os.Stdout = f
+
+	t.Cleanup(func() {
+		os.Stdout = saved
+
+		_ = f.Close()
+	})
+
+	return func() string {
+		// Read what has been written without disturbing the write
+		// offset, so the capture can be inspected more than once.
+		size, err := f.Seek(0, io.SeekCurrent)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		if size == 0 {
+			return ""
+		}
+
+		b := make([]byte, size)
+
+		_, err = f.ReadAt(b, 0)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		return string(b)
+	}
+}
+
+// brokenDatabase writes a database that opens cleanly and passes the
+// schema-version check but has no files table, so the first query
+// fails with the database already open: a fatal error on a path that
+// owns an open database.
+func brokenDatabase(t *testing.T) string {
+	t.Helper()
+
+	path := testDBPath(t)
+
+	db, err := openDB(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.ExecContext(context.Background(),
+		"PRAGMA user_version = "+strconv.Itoa(schemaVersion))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = db.Close()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return path
+}
+
+func TestOpenDatabaseKeepsWALWhileOpen(t *testing.T) {
+	t.Parallel()
+
+	// The premise of the fatal-path tests below: an open database has
+	// a -wal sidecar, so its absence afterwards is evidence that the
+	// database was closed and its WAL checkpointed.
+	path := testDBPath(t)
+
+	db, err := openScanDatabase(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = os.Stat(path + "-wal")
+	if err != nil {
+		t.Fatalf("no -wal beside an open database: %v", err)
+	}
+
+	err = db.Close()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assertNoSidecars(t, path)
+}
+
+func TestRunFatalAfterOpenClosesDatabase(t *testing.T) {
+	// Every subcommand that owns an open database must close it when
+	// it fails: no os.Exit between the open and the return.
+	cases := map[string][]string{
+		cmdScan:   {cmdScan},
+		cmdReport: {cmdReport},
+		cmdTrees:  {cmdTrees},
+	}
+
+	for name, args := range cases {
+		t.Run(name, func(t *testing.T) {
+			path := brokenDatabase(t)
+			t.Setenv(databaseEnv, path)
+
+			if name == cmdScan {
+				args = append(args, t.TempDir())
+			}
+
+			var stderr bytes.Buffer
+
+			stdout := captureStdout(t)
+
+			code := run(args, &stderr)
+			if code != exitFatal {
+				t.Errorf("run(%v) = %d, want %d", args, code, exitFatal)
+			}
+
+			assertNoSidecars(t, path)
+			assertFatalOutput(t, stderr.String(), stdout())
+
+			// Proof that the failure happened after the open: only a
+			// query against the opened database can report this.
+			if !strings.Contains(stderr.String(), "no such table: files") {
+				t.Errorf("stderr = %q, want the failure to come from a "+
+					"query on the open database", stderr.String())
+			}
+		})
+	}
+}
+
+func TestRunMissingOperandIsFatalNotUsage(t *testing.T) {
+	// README §Error handling: a PATH operand that does not exist is a
+	// fatal error (1), not a usage error (2) — and a runtime failure
+	// must not dump the usage text.
+	t.Setenv(databaseEnv, testDBPath(t))
+
+	var stderr bytes.Buffer
+
+	stdout := captureStdout(t)
+
+	missing := filepath.Join(t.TempDir(), "nope")
+
+	code := run([]string{cmdScan, missing}, &stderr)
+	if code != exitFatal {
+		t.Errorf("run(scan %s) = %d, want %d", missing, code, exitFatal)
+	}
+
+	assertFatalOutput(t, stderr.String(), stdout())
+}
+
+// assertFatalOutput checks that a fatal error was reported the way
+// README §Error handling and design goal 4 require: the message on
+// stderr, prefixed with the program name, no usage text, and nothing
+// at all on stdout.
+func assertFatalOutput(t *testing.T, stderr, stdout string) {
+	t.Helper()
+
+	if !strings.Contains(stderr, "sfdupes: ") {
+		t.Errorf("stderr = %q, want a \"sfdupes: \" error report", stderr)
+	}
+
+	if strings.Contains(stderr, usageMarker) {
+		t.Errorf("stderr = %q, want no usage text for a runtime failure",
+			stderr)
+	}
+
+	if stdout != "" {
+		t.Errorf("stdout = %q, want nothing (data only)", stdout)
+	}
+}
+
+func TestRunUsageErrors(t *testing.T) {
+	// Usage errors keep exiting 2 with cobra's own report on stderr.
+	cases := map[string]struct {
+		args []string
+		want string
+	}{
+		"no subcommand":      {[]string{}, usageMarker},
+		"scan without paths": {[]string{cmdScan}, usageMarker},
+		"report with args":   {[]string{cmdReport, "x"}, usageMarker},
+		"trees with args":    {[]string{cmdTrees, "x"}, usageMarker},
+		"unknown flag":       {[]string{cmdScan, "--nope", "/"}, usageMarker},
+		"unknown subcommand": {[]string{"nope"}, "unknown command"},
+	}
+
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			// No usage error may reach the database, so point it at a
+			// path that does not exist.
+			t.Setenv(databaseEnv, testDBPath(t))
+
+			var stderr bytes.Buffer
+
+			stdout := captureStdout(t)
+
+			code := run(tc.args, &stderr)
+			if code != exitUsage {
+				t.Errorf("run(%v) = %d, want %d", tc.args, code, exitUsage)
+			}
+
+			if !strings.Contains(stderr.String(), tc.want) {
+				t.Errorf("stderr = %q, want %q", stderr.String(), tc.want)
+			}
+
+			if got := stdout(); got != "" {
+				t.Errorf("stdout = %q, want nothing (data only)", got)
+			}
+		})
+	}
+}
+
+// TestRunHelpAndVersionSucceed checks that the two informational flags
+// exit 0 and keep their human-facing output on stderr.
+//
+//nolint:paralleltest // captureStdout replaces the process-wide os.Stdout
+func TestRunHelpAndVersionSucceed(t *testing.T) {
+	assertHumanOutput(t, "--help")
+	assertHumanOutput(t, "--version")
+}
+
+// assertHumanOutput runs sfdupes with one informational flag and checks
+// that it succeeds with its output on stderr and stdout untouched
+// (README design goal 4).
+func assertHumanOutput(t *testing.T, arg string) {
+	t.Helper()
+
+	var stderr bytes.Buffer
+
+	stdout := captureStdout(t)
+
+	code := run([]string{arg}, &stderr)
+	if code != exitOK {
+		t.Errorf("run(%s) = %d, want %d", arg, code, exitOK)
+	}
+
+	if stderr.Len() == 0 {
+		t.Errorf("run(%s) wrote nothing to stderr", arg)
+	}
+
+	if got := stdout(); got != "" {
+		t.Errorf("stdout = %q, want nothing (data only)", got)
+	}
+}
+
+// scanFixture builds a small tree holding one duplicate pair and one
+// unreadable file and scans it into the database the caller has
+// pointed SFDUPES_DATABASE at. The unreadable file makes the scan warn
+// and skip, which README §Error handling still calls a successful run.
+// It returns the duplicate pair's paths.
+func scanFixture(t *testing.T) []string {
+	t.Helper()
+
+	dir := t.TempDir()
+
+	dupes := []string{
+		writeFile(t, dir, "one/a.bin", pattern(1, 300)),
+		writeFile(t, dir, "two/a.bin", pattern(1, 300)),
+	}
+
+	// Same size as the pair, so the scan queues it for hashing and the
+	// read fails.
+	unreadable := writeFile(t, dir, "unreadable.bin", pattern(2, 300))
+
+	err := os.Chmod(unreadable, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var stderr bytes.Buffer
+
+	stdout := captureStdout(t)
+
+	code := run([]string{cmdScan, dir}, &stderr)
+	if code != exitOK {
+		t.Fatalf("run(scan) = %d, want %d; stderr: %s",
+			code, exitOK, stderr.String())
+	}
+
+	if got := stdout(); got != "" {
+		t.Errorf("scan stdout = %q, want nothing (data only)", got)
+	}
+
+	return dupes
+}
+
+func TestRunScanSucceedsDespiteWarnings(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	scanFixture(t)
+	assertNoSidecars(t, path)
+}
+
+func TestRunReportSucceeds(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dupes := scanFixture(t)
+
+	var stderr bytes.Buffer
+
+	stdout := captureStdout(t)
+
+	code := run([]string{cmdReport}, &stderr)
+	if code != exitOK {
+		t.Fatalf("run(report) = %d, want %d; stderr: %s",
+			code, exitOK, stderr.String())
+	}
+
+	want := "first\tdupe\tsize\n" + dupes[0] + "\t" + dupes[1] + "\t300\n"
+	if got := stdout(); got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+
+	assertNoSidecars(t, path)
+}
+
+func TestRunTreesSucceeds(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dupes := scanFixture(t)
+
+	var stderr bytes.Buffer
+
+	stdout := captureStdout(t)
+
+	code := run([]string{cmdTrees}, &stderr)
+	if code != exitOK {
+		t.Fatalf("run(trees) = %d, want %d; stderr: %s",
+			code, exitOK, stderr.String())
+	}
+
+	// The two directories holding the duplicate pair are duplicate
+	// trees of each other.
+	want := "first\tdupe\tfiles\tsize\n" +
+		filepath.Dir(dupes[0]) + "\t" + filepath.Dir(dupes[1]) + "\t1\t300\n"
+	if got := stdout(); got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+
+	assertNoSidecars(t, path)
+}

report.go

@@ -28,23 +28,26 @@ type scanRec struct {
 
 // loadRecords opens the database and reads every file record for the
 // report and trees subcommands. Any database problem — including a
-// missing database — is fatal.
-func loadRecords() []scanRec {
+// missing database — is fatal. The error is returned rather than
+// exiting, so that the deferred close — which checkpoints the SQLite
+// WAL — always runs; the database is closed before the caller formats
+// its output, so it stays closed even if that output fails.
+func loadRecords() ([]scanRec, error) {
 	dbPath := databasePath()
 
 	db, err := openReportDatabase(dbPath)
 	if err != nil {
-		fatalf("%v", err)
+		return nil, err
 	}
 
 	defer func() { _ = db.Close() }()
 
 	recs, err := loadFileRows(db)
 	if err != nil {
-		fatalf("database %s: %v", dbPath, err)
+		return nil, fmt.Errorf("database %s: %w", dbPath, err)
 	}
 
-	return recs
+	return recs, nil
 }
 
 // dupeGroup is one set of candidate-duplicate files: identical size,
@@ -59,15 +62,19 @@ type dupeGroup struct {
 // from the database and 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.
-func runReport() {
-	recs := loadRecords()
+func runReport() error {
+	recs, err := loadRecords()
+	if err != nil {
+		return err
+	}
+
 	dupes := collectDupeGroups(recs)
 
 	out := bufio.NewWriterSize(os.Stdout, ioBufSize)
 
-	_, err := fmt.Fprintln(out, "first\tdupe\tsize")
+	_, err = fmt.Fprintln(out, "first\tdupe\tsize")
 	if err != nil {
-		fatalf("write stdout: %v", err)
+		return fmt.Errorf("write stdout: %w", err)
 	}
 
 	dupeFiles := 0
@@ -79,7 +86,7 @@ func runReport() {
 			_, err = fmt.Fprintf(out, "%s\t%s\t%d\n",
 				g.paths[0], p, g.size)
 			if err != nil {
-				fatalf("write stdout: %v", err)
+				return fmt.Errorf("write stdout: %w", err)
 			}
 
 			dupeFiles++
@@ -89,13 +96,15 @@ func runReport() {
 
 	err = out.Flush()
 	if err != nil {
-		fatalf("write stdout: %v", err)
+		return fmt.Errorf("write stdout: %w", err)
 	}
 
 	fmt.Fprintf(os.Stderr,
 		"report: %d records read, %d duplicate groups, %d dupe files, "+
 			"%s reclaimable\n",
 		len(recs), len(dupes), dupeFiles, humanBytes(reclaimable))
+
+	return nil
 }
 
 // collectDupeGroups groups records by signature and returns every group

scan.go

@@ -49,25 +49,30 @@ type fileMeta struct {
 // under the PATH operands. Only files whose size at least one other
 // file shares are ever hashed: a size-unique file cannot be a
 // duplicate. Flag parsing and the at-least-one-operand check are done
-// by cobra.
-func runScan(roots []string, workers int, oneFS bool) {
+// by cobra. Errors are returned rather than exiting, so that the
+// deferred close — which checkpoints the SQLite WAL — always runs.
+func runScan(roots []string, workers int, oneFS bool) error {
 	if workers < 1 {
 		workers = 1
 	}
 
-	roots = resolveRoots(roots)
+	roots, err := resolveRoots(roots)
+	if err != nil {
+		return err
+	}
+
 	dbPath := databasePath()
 
 	db, err := openScanDatabase(dbPath)
 	if err != nil {
-		fatalf("%v", err)
+		return err
 	}
 
 	defer func() { _ = db.Close() }()
 
 	st, err := syncScan(db, roots, workers, oneFS)
 	if err != nil {
-		fatalf("update database %s: %v", dbPath, err)
+		return fmt.Errorf("update database %s: %w", dbPath, err)
 	}
 
 	fmt.Fprintf(os.Stderr,
@@ -75,31 +80,33 @@ func runScan(roots []string, workers int, oneFS bool) {
 			"%d unchanged), %d skipped\n",
 		st.added+st.updated+st.unchanged, st.added, st.updated,
 		st.removed, st.unchanged, st.skipped)
+
+	return nil
 }
 
 // resolveRoots converts each PATH operand to an absolute, lexically
 // cleaned path (symlinks are not resolved) and verifies that it
 // exists. Database records are keyed by absolute path, so scan results
 // must not depend on the working directory.
-func resolveRoots(roots []string) []string {
+func resolveRoots(roots []string) ([]string, error) {
 	abs := make([]string, 0, len(roots))
 
 	for _, root := range roots {
 		a, err := filepath.Abs(root)
 		if err != nil {
-			fatalf("resolve %s: %v", root, err)
+			return nil, fmt.Errorf("resolve %s: %w", root, err)
 		}
 
 		// A nonexistent operand is a fatal error before any scanning.
 		_, err = os.Lstat(a)
 		if err != nil {
-			fatalf("%v", err)
+			return nil, err
 		}
 
 		abs = append(abs, a)
 	}
 
-	return abs
+	return abs, nil
 }
 
 // pruneRoots drops operands already covered by another operand:

trees.go

@@ -34,8 +34,11 @@ type treeNode struct {
 // maximal duplicate-tree groups as TSV on stdout. It never touches the
 // scanned filesystem; its only I/O is the database, stdout, and
 // stderr.
-func runTrees() {
-	recs := loadRecords()
+func runTrees() error {
+	recs, err := loadRecords()
+	if err != nil {
+		return err
+	}
 
 	super, allDirs := buildHierarchy(recs)
 	super.compute()
@@ -44,9 +47,9 @@ func runTrees() {
 
 	out := bufio.NewWriterSize(os.Stdout, ioBufSize)
 
-	_, err := fmt.Fprintln(out, "first\tdupe\tfiles\tsize")
+	_, err = fmt.Fprintln(out, "first\tdupe\tfiles\tsize")
 	if err != nil {
-		fatalf("write stdout: %v", err)
+		return fmt.Errorf("write stdout: %w", err)
 	}
 
 	dupeTrees := 0
@@ -59,7 +62,7 @@ func runTrees() {
 			_, err = fmt.Fprintf(out, "%s\t%s\t%d\t%d\n",
 				first.path, n.path, first.fileCount, first.totalSize)
 			if err != nil {
-				fatalf("write stdout: %v", err)
+				return fmt.Errorf("write stdout: %w", err)
 			}
 
 			dupeTrees++
@@ -69,13 +72,15 @@ func runTrees() {
 
 	err = out.Flush()
 	if err != nil {
-		fatalf("write stdout: %v", err)
+		return fmt.Errorf("write stdout: %w", err)
 	}
 
 	fmt.Fprintf(os.Stderr,
 		"trees: %d records read, %d duplicate tree groups, %d dupe trees, "+
 			"%s reclaimable\n",
 		len(recs), len(dupes), dupeTrees, humanBytes(reclaimable))
+
+	return nil
 }
 
 // buildHierarchy reconstructs the directory hierarchy from the record