Hold a lock so a second scan fails at once (closes #53)

scan takes an exclusive flock(2) on a lock file beside the database
(its path with .lock appended) before it walks anything or opens the
database, and holds it until it returns. A second scan against the
same database fails at once with a one-line error naming the lock
file and exits 1. report and trees never take the lock. The lock ends
with the process, so a fatal error or an interrupt releases it; the
file is never deleted. golang.org/x/sys becomes a direct dependency.

The README smoke test now keeps the database outside the scanned
tree, where its empty lock file would have joined the empty-file
group.

Model: opus-5-5

.gitea/workflows/check.yml

@@ -6,4 +6,6 @@ jobs:
         steps:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+              with:
+                  fetch-depth: 0
             - run: script/cibuild

README.md

@@ -113,8 +113,9 @@ Goals, in order:
     `sfdupes`.
 -   Dependencies: standard library, `github.com/spf13/cobra` for the
     CLI, **one progress-bar library**
-    (`github.com/schollz/progressbar/v3`), and **one SQLite driver**
-    (`modernc.org/sqlite`, pure Go, so builds keep cgo disabled).
+    (`github.com/schollz/progressbar/v3`), **one SQLite driver**
+    (`modernc.org/sqlite`, pure Go, so builds keep cgo disabled), and
+    `golang.org/x/sys` for `flock(2)` (the scan lock, see "Database").
     `github.com/spf13/viper` is permitted if configuration-file support
     is ever needed, but is not currently used. No other third-party
     deps.
@@ -152,16 +153,42 @@ All three subcommands operate on a single SQLite database file:
     use. `report` and `trees` require an existing database; a missing
     database file is a fatal error (exit 1) telling the user to run
     `scan` first.
--   The database uses WAL journal mode and a busy timeout, so running a
-    report while a cron `scan` is in progress is safe. The filesystem
-    is authoritative; the database is an eventually-consistent
-    reflection of it. Hashed records are committed in batched
-    transactions while the scan is still running (keeping the WAL
-    small and letting concurrent reports observe progress), so a
-    report may see a scan's changes partially applied, and a scan
-    that dies partway leaves a valid database holding everything
-    hashed so far; the next scan skips those records and converges
-    toward the filesystem.
+-   Only one `scan` runs against a database at a time. For its whole
+    run, `scan` holds an exclusive `flock(2)` lock on a lock file
+    beside the database, named by appending `.lock` to the database
+    path (`/var/lib/sfdupes/db.sqlite.lock` by default), taken before
+    it walks the filesystem or opens the database. A second `scan`
+    against the same database does not wait: it fails at once with a
+    one-line error naming the lock file and exits 1, without walking
+    anything or opening the database, and the running scan carries on.
+    The lock file is created on first use, open to its owner only, and
+    left in place: a leftover file blocks nothing, because the lock
+    ends with the process holding it however it ends, a fatal error or
+    an interrupt included, and deleting the file while a scan runs
+    would let a second scan start. `report` and `trees` never take the
+    lock, so they run during a scan.
+-   While `scan` runs, the database is in WAL journal mode with a busy
+    timeout, so running a report while a cron `scan` is in progress is
+    safe. The filesystem is authoritative; the database is an
+    eventually-consistent reflection of it. Hashed records are
+    committed in batched transactions while the scan is still running
+    (keeping the WAL small and letting concurrent reports observe
+    progress), so a report may see a scan's changes partially applied,
+    and a scan that dies partway leaves a valid database holding
+    everything hashed so far; the next scan skips those records and
+    converges toward the filesystem.
+-   `scan` switches the database back to rollback-journal mode when it
+    closes it, so between scans the database file alone holds the whole
+    database. Each switch needs the database to itself: a `scan` that
+    starts while a report is still reading waits for it up to the
+    10-second busy timeout, then fails; a `scan` that ends while a
+    report has the database open warns and leaves the database in WAL
+    mode until the next scan.
+-   `report` and `trees` open the database read-only and need only read
+    access to the database file, and no write access to its directory.
+    While the database is in WAL mode they also read the `-wal` and
+    `-shm` files beside it, which SQLite creates with the database
+    file's permissions.
 -   Schema (`PRAGMA user_version` is the schema version, currently 1; a
     database with any other version is a fatal error):
 
@@ -428,6 +455,15 @@ first	dupe	size
 /srv/a/big.iso	/srv/c/big-copy2.iso	4294967296
 ```
 
+Paths are raw bytes and may hold any byte except NUL, so the path
+columns (`first` and `dupe`) are escaped to keep every row one line of
+tab-separated fields: a backslash is written as `\\`, a tab as `\t`, a
+newline as `\n`, and a carriage return as `\r`. Every other byte is
+written unchanged, including bytes that are not valid UTF-8. Undoing
+those four escapes gives back the stored path. Grouping and ordering
+use the stored path, not the escaped one. The warnings `scan` prints on
+stderr are escaped the same way, so each warning is one line.
+
 Summary to stderr: records read, number of duplicate groups, number of
 dupe files, and total reclaimable bytes (sum of `size` over all dupe
 rows) in human units.
@@ -499,6 +535,9 @@ first	dupe	files	size
 /srv/a/project	/srv/backup/project	3417	104857600
 ```
 
+The `first` and `dupe` paths are escaped as described under "Report
+output format". The root directory's path is `/`.
+
 Summary to stderr: records read, number of duplicate-tree groups,
 number of dupe trees, and total reclaimable bytes (sum of `size` over
 all dupe rows) in human units.
@@ -543,12 +582,25 @@ Additional requirements:
 ### Error handling and exit codes
 
 -   `0`: success, even if individual files were skipped with warnings.
--   `1`: fatal error (e.g., a `PATH` operand does not exist, the
-    database cannot be created/opened/read/written, a missing database
-    for `report`/`trees`, stdout write failure).
+-   `1`: fatal error (e.g., a `PATH` operand does not exist, another
+    `scan` is already running against the same database, the database
+    cannot be created/opened/read/written, a missing database for
+    `report`/`trees`, stdout write failure).
 -   `2`: usage error (including `scan` with no `PATH` operand and
     `report`/`trees` with any positional argument).
 
+A stdout write failure, such as a full disk, is reported in one line on
+stderr and exits 1. Two cases never reach sfdupes as a failed write:
+
+-   When the reader of a stdout pipe exits early, as in
+    `sfdupes report | head`, the next write ends sfdupes with `SIGPIPE`,
+    quietly and without a summary, the way `cat` or `sort` end. The
+    shell reports the signal (status 141 in most shells), not exit 1.
+-   When stdout is closed outright (`sfdupes report >&-`), the Go
+    runtime opens `/dev/null` in its place before sfdupes starts, so
+    the output is discarded and the run succeeds, as with
+    `> /dev/null`.
+
 ## Entrypoints
 
 This repository adheres to the
@@ -686,7 +738,7 @@ All of the following, run in this directory, must pass:
 
     ```sh
     d=$(mktemp -d)
-    export SFDUPES_DATABASE="$d/db.sqlite"
+    export SFDUPES_DATABASE="$(mktemp -d)/db.sqlite"
     mkdir -p "$d/a" "$d/b"
     head -c 2000 /dev/urandom > "$d/a/one.bin"
     cp "$d/a/one.bin" "$d/b/copy.bin"
@@ -714,9 +766,9 @@ All of the following, run in this directory, must pass:
     ./sfdupes report
     ```
 
-    (The scan database lives inside `$d` here purely for test hygiene;
-    scanning `$d` therefore also records the SQLite file itself, which
-    is harmless.)
+    (The database lives in a temp directory of its own: inside `$d`,
+    the scan would record it, and its empty lock file would join the
+    `empty1`/`empty2` group.)
 
     Expected from the first `report`: `one.bin`/`copy.bin`/`copy2.bin`
     form one group (two dupe rows, `first` is the lexicographically

TODO.md

@@ -29,6 +29,22 @@
 
 # Completed Steps
 
+- `scan` holds a lock on a lock file beside the database for its whole run,
+  so a second `scan` fails at once with exit 1 (2026-10-03,
+  https://git.eeqj.de/sneak/sfdupes/issues/53)
+
+- test stdout write failures in `report` and `trees`; README states that
+  `| head` ends sfdupes by `SIGPIPE` and `>&-` writes to `/dev/null`
+  (2026-10-03, https://git.eeqj.de/sneak/sfdupes/issues/30)
+
+- `report` and `trees` open the database read-only, and `scan` leaves it
+  out of WAL mode, so reading needs only read access (2026-10-03, closes
+  https://git.eeqj.de/sneak/sfdupes/issues/8)
+
+- escape tabs, newlines, carriage returns and backslashes in report,
+  trees and warning paths; the root directory's path is `/`
+  (2026-10-03, https://git.eeqj.de/sneak/sfdupes/issues/7)
+
 - stamp the git tag or short commit in a plain `docker build .`
   instead of `dev` (2026-10-02, branch `next`, closes
   https://git.eeqj.de/sneak/sfdupes/issues/67): `.dockerignore` now
@@ -36,7 +52,9 @@
   stage takes the `VERSION` build argument when one is given,
   otherwise `git describe --tags --always` of that `.git`. The build
   fails if the context carries `.git` and the version still comes out
-  empty, `dev` or `unknown`.
+  empty, `dev` or `unknown`. The CI checkout step fetches the full
+  history (`fetch-depth: 0`) so CI sees the tag and stamps the same
+  value as `make build`.
 
 - replace the 1 KiB end-window sampling with the head/tail plus
   content-hash ladder (2026-09-22, branch `next`, closes

db.go

@@ -11,6 +11,7 @@ import (
 	"slices"
 	"strconv"
 
+	"golang.org/x/sys/unix"
 	// The pure-Go SQLite driver, registered as "sqlite"; keeps cgo
 	// disabled.
 	_ "modernc.org/sqlite"
@@ -32,6 +33,11 @@ const schemaVersion = 1
 // scan.
 const dbDirPerm = 0o755
 
+// 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.
 const createTableSQL = `
@@ -64,6 +70,10 @@ var errNoDatabase = errors.New(
 // 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")
+
 // databasePath resolves the database location: SFDUPES_DATABASE when
 // set and non-empty, the compiled-in default otherwise.
 func databasePath() string {
@@ -74,16 +84,24 @@ func databasePath() string {
 	return defaultDatabasePath
 }
 
-// openDB opens the SQLite database at path with WAL journaling and a
-// busy timeout, so a report can run while a cron scan is in progress.
-// It does not create or verify the schema.
-func openDB(path string) (*sql.DB, error) {
-	dsn := "file:" + path +
-		"?_pragma=busy_timeout(10000)" +
-		"&_pragma=journal_mode(WAL)" +
-		"&_pragma=synchronous(NORMAL)"
+// 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.
+const scanParams = "_pragma=busy_timeout(10000)" +
+	"&_pragma=journal_mode(WAL)" +
+	"&_pragma=synchronous(NORMAL)"
 
-	db, err := sql.Open("sqlite", dsn)
+// reportParams are the connection parameters for report and trees:
+// 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) {
+	db, err := sql.Open("sqlite", "file:"+path+"?"+params)
 	if err != nil {
 		return nil, fmt.Errorf("open database %s: %w", path, err)
 	}
@@ -96,6 +114,43 @@ func openDB(path string) (*sql.DB, error) {
 	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
+// path with ".lock" appended, created along with the database's parent
+// directory if missing. 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 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 := os.MkdirAll(filepath.Dir(path), dbDirPerm)
+	if err != nil {
+		return nil, fmt.Errorf("create database directory: %w", err)
+	}
+
+	lockPath := path + ".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) {
@@ -104,7 +159,7 @@ func openScanDatabase(ctx context.Context, path string) (*sql.DB, error) {
 		return nil, fmt.Errorf("create database directory: %w", err)
 	}
 
-	db, err := openDB(path)
+	db, err := openDB(path, scanParams)
 	if err != nil {
 		return nil, err
 	}
@@ -119,6 +174,24 @@ func openScanDatabase(ctx context.Context, path string) (*sql.DB, error) {
 	return db, 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 and
 // trees subcommands. A missing database file is an error directing the
 // user to run scan first; the schema version must match exactly.
@@ -134,7 +207,7 @@ func openReportDatabase(ctx context.Context,
 		return nil, fmt.Errorf("database: %w", err)
 	}
 
-	db, err := openDB(path)
+	db, err := openDB(path, reportParams)
 	if err != nil {
 		return nil, err
 	}

db_test.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"errors"
 	"fmt"
+	"os"
 	"path/filepath"
 	"slices"
 	"strings"
@@ -130,6 +131,49 @@ func TestOpenReportDatabaseOK(t *testing.T) {
 	_ = 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)
+	if err != nil {
+		t.Fatalf("loadFileRows: %v", err)
+	}
+}
+
 func TestApplyChangesRoundTrip(t *testing.T) {
 	t.Parallel()
 

go.mod

@@ -5,6 +5,7 @@ go 1.25.7
 require (
 	github.com/schollz/progressbar/v3 v3.19.1
 	github.com/spf13/cobra v1.10.2
+	golang.org/x/sys v0.46.0
 	modernc.org/sqlite v1.54.0
 )
 
@@ -18,7 +19,6 @@ require (
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
-	golang.org/x/sys v0.46.0 // indirect
 	golang.org/x/term v0.44.0 // indirect
 	modernc.org/libc v1.74.1 // indirect
 	modernc.org/mathutil v1.7.1 // indirect

main.go

@@ -57,22 +57,27 @@ var errNoSubcommand = errors.New("no subcommand")
 var Version = "dev"
 
 func main() {
-	os.Exit(run(os.Args[1:], os.Stderr))
+	// 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.
+	os.Exit(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.
-func run(args []string, stderr io.Writer) int {
+// runs before the process ends. The report and trees 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(stderr)
+	root := newRootCommand(stdout, stderr)
 	root.SetArgs(args)
 
 	err := root.Execute()
@@ -98,7 +103,7 @@ func run(args []string, stderr io.Writer) int {
 // 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 {
+func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 	root := &cobra.Command{
 		Use:     "sfdupes",
 		Short:   "Find candidate duplicate files by size and head/tail/content SHA-256",
@@ -140,7 +145,7 @@ func newRootCommand(stderr io.Writer) *cobra.Command {
 		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)
+			return runReport(ctx, stdout)
 		}),
 	}
 
@@ -149,7 +154,7 @@ func newRootCommand(stderr io.Writer) *cobra.Command {
 		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)
+			return runTrees(ctx, stdout)
 		}),
 	}
 

main_test.go

@@ -44,60 +44,54 @@ func assertNoSidecars(t *testing.T, path string) {
 	}
 }
 
-// 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 {
+// makeReadOnly takes write permission away from the database at path,
+// from any WAL sidecar beside it, and from their directory, as for a
+// user reading a database that a root cron scan keeps. Root ignores
+// file permissions, so it skips the test when run as root.
+func makeReadOnly(t *testing.T, path string) {
 	t.Helper()
 
-	f, err := os.Create(filepath.Join(t.TempDir(), "stdout"))
+	if os.Geteuid() == 0 {
+		t.Skip("root ignores file permissions")
+	}
+
+	err := os.Chmod(path, 0o400)
 	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 {
+	for _, suffix := range walSuffixes {
+		err = os.Chmod(path+suffix, 0o400)
+		if err != nil && !errors.Is(err, fs.ErrNotExist) {
 			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)
 	}
+
+	dir := filepath.Dir(path)
+
+	//nolint:gosec // reaching the database needs the search bit
+	err = os.Chmod(dir, 0o500)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Runs before t.TempDir's own cleanup, which must delete the files.
+	t.Cleanup(func() {
+		//nolint:gosec // removing the directory needs its search bit back
+		_ = os.Chmod(dir, 0o700)
+	})
 }
 
 // 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.
+// owns an open database. It closes the database the way scan does.
 func brokenDatabase(t *testing.T) string {
 	t.Helper()
 
 	path := testDBPath(t)
 
-	db, err := openDB(path)
+	db, err := openDB(path, scanParams)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -108,10 +102,7 @@ func brokenDatabase(t *testing.T) string {
 		t.Fatal(err)
 	}
 
-	err = db.Close()
-	if err != nil {
-		t.Fatal(err)
-	}
+	closeScanDatabase(t.Context(), db, path)
 
 	return path
 }
@@ -144,7 +135,10 @@ func TestOpenDatabaseKeepsWALWhileOpen(t *testing.T) {
 
 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.
+	// it fails: no os.Exit between the open and the return. The
+	// sidecar check is evidence of the close only for scan: report and
+	// trees only read a database that is out of WAL mode, which leaves
+	// nothing on disk whether they close it or not.
 	cases := map[string][]string{
 		cmdScan:   {cmdScan},
 		cmdReport: {cmdReport},
@@ -160,17 +154,15 @@ func TestRunFatalAfterOpenClosesDatabase(t *testing.T) {
 				args = append(args, t.TempDir())
 			}
 
-			var stderr bytes.Buffer
+			var stdout, stderr bytes.Buffer
 
-			stdout := captureStdout(t)
-
-			code := run(args, &stderr)
+			code := run(args, &stdout, &stderr)
 			if code != exitFatal {
 				t.Errorf("run(%v) = %d, want %d", args, code, exitFatal)
 			}
 
 			assertNoSidecars(t, path)
-			assertFatalOutput(t, stderr.String(), stdout())
+			assertFatalOutput(t, stderr.String(), stdout.String())
 
 			// Proof that the failure happened after the open: only a
 			// query against the opened database can report this.
@@ -188,18 +180,16 @@ func TestRunMissingOperandIsFatalNotUsage(t *testing.T) {
 	// must not dump the usage text.
 	t.Setenv(databaseEnv, testDBPath(t))
 
-	var stderr bytes.Buffer
-
-	stdout := captureStdout(t)
+	var stdout, stderr bytes.Buffer
 
 	missing := filepath.Join(t.TempDir(), "nope")
 
-	code := run([]string{cmdScan, missing}, &stderr)
+	code := run([]string{cmdScan, missing}, &stdout, &stderr)
 	if code != exitFatal {
 		t.Errorf("run(scan %s) = %d, want %d", missing, code, exitFatal)
 	}
 
-	assertFatalOutput(t, stderr.String(), stdout())
+	assertFatalOutput(t, stderr.String(), stdout.String())
 }
 
 // assertFatalOutput checks that a fatal error was reported the way
@@ -243,11 +233,9 @@ func TestRunUsageErrors(t *testing.T) {
 			// path that does not exist.
 			t.Setenv(databaseEnv, testDBPath(t))
 
-			var stderr bytes.Buffer
+			var stdout, stderr bytes.Buffer
 
-			stdout := captureStdout(t)
-
-			code := run(tc.args, &stderr)
+			code := run(tc.args, &stdout, &stderr)
 			if code != exitUsage {
 				t.Errorf("run(%v) = %d, want %d", tc.args, code, exitUsage)
 			}
@@ -256,7 +244,7 @@ func TestRunUsageErrors(t *testing.T) {
 				t.Errorf("stderr = %q, want %q", stderr.String(), tc.want)
 			}
 
-			if got := stdout(); got != "" {
+			if got := stdout.String(); got != "" {
 				t.Errorf("stdout = %q, want nothing (data only)", got)
 			}
 		})
@@ -265,9 +253,9 @@ func TestRunUsageErrors(t *testing.T) {
 
 // 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) {
+	t.Parallel()
+
 	assertHumanOutput(t, "--help")
 	assertHumanOutput(t, "--version")
 }
@@ -278,11 +266,9 @@ func TestRunHelpAndVersionSucceed(t *testing.T) {
 func assertHumanOutput(t *testing.T, arg string) {
 	t.Helper()
 
-	var stderr bytes.Buffer
+	var stdout, stderr bytes.Buffer
 
-	stdout := captureStdout(t)
-
-	code := run([]string{arg}, &stderr)
+	code := run([]string{arg}, &stdout, &stderr)
 	if code != exitOK {
 		t.Errorf("run(%s) = %d, want %d", arg, code, exitOK)
 	}
@@ -291,7 +277,7 @@ func assertHumanOutput(t *testing.T, arg string) {
 		t.Errorf("run(%s) wrote nothing to stderr", arg)
 	}
 
-	if got := stdout(); got != "" {
+	if got := stdout.String(); got != "" {
 		t.Errorf("stdout = %q, want nothing (data only)", got)
 	}
 }
@@ -320,17 +306,15 @@ func scanFixture(t *testing.T) []string {
 		t.Fatal(err)
 	}
 
-	var stderr bytes.Buffer
+	var stdout, stderr bytes.Buffer
 
-	stdout := captureStdout(t)
-
-	code := run([]string{cmdScan, dir}, &stderr)
+	code := run([]string{cmdScan, dir}, &stdout, &stderr)
 	if code != exitOK {
 		t.Fatalf("run(scan) = %d, want %d; stderr: %s",
 			code, exitOK, stderr.String())
 	}
 
-	if got := stdout(); got != "" {
+	if got := stdout.String(); got != "" {
 		t.Errorf("scan stdout = %q, want nothing (data only)", got)
 	}
 
@@ -351,18 +335,16 @@ func TestRunReportSucceeds(t *testing.T) {
 
 	dupes := scanFixture(t)
 
-	var stderr bytes.Buffer
+	var stdout, stderr bytes.Buffer
 
-	stdout := captureStdout(t)
-
-	code := run([]string{cmdReport}, &stderr)
+	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" + dupes[0] + "\t" + dupes[1] + "\t300\n"
-	if got := stdout(); got != want {
+	if got := stdout.String(); got != want {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
 
@@ -375,11 +357,9 @@ func TestRunTreesSucceeds(t *testing.T) {
 
 	dupes := scanFixture(t)
 
-	var stderr bytes.Buffer
+	var stdout, stderr bytes.Buffer
 
-	stdout := captureStdout(t)
-
-	code := run([]string{cmdTrees}, &stderr)
+	code := run([]string{cmdTrees}, &stdout, &stderr)
 	if code != exitOK {
 		t.Fatalf("run(trees) = %d, want %d; stderr: %s",
 			code, exitOK, stderr.String())
@@ -389,9 +369,197 @@ func TestRunTreesSucceeds(t *testing.T) {
 	// 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 {
+	if got := stdout.String(); got != want {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
 
 	assertNoSidecars(t, path)
 }
+
+func TestRunReportsNeedOnlyReadAccess(t *testing.T) {
+	// README §Database: report and trees need only read access to the
+	// database file. With its directory read-only as well, SQLite
+	// cannot create any file beside it.
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dupes := scanFixture(t)
+	assertNoSidecars(t, path)
+	makeReadOnly(t, path)
+
+	cases := map[string]string{
+		cmdReport: "first\tdupe\tsize\n" +
+			dupes[0] + "\t" + dupes[1] + "\t300\n",
+		cmdTrees: "first\tdupe\tfiles\tsize\n" +
+			filepath.Dir(dupes[0]) + "\t" + filepath.Dir(dupes[1]) +
+			"\t1\t300\n",
+	}
+
+	for name, want := range cases {
+		var stdout, stderr bytes.Buffer
+
+		code := run([]string{name}, &stdout, &stderr)
+		if code != exitOK {
+			t.Errorf("run(%s) = %d, want %d; stderr: %s",
+				name, code, exitOK, stderr.String())
+
+			continue
+		}
+
+		if got := stdout.String(); got != want {
+			t.Errorf("%s stdout = %q, want %q", name, got, want)
+		}
+	}
+}
+
+// holdScanLock takes the lock on the database at path, as a running
+// scan does, and holds it until the test ends. It fails the test when
+// the lock is already held.
+func holdScanLock(t *testing.T, path string) {
+	t.Helper()
+
+	lock, err := lockScanDatabase(path)
+	if err != nil {
+		t.Fatalf("lock %s: %v", path, err)
+	}
+
+	t.Cleanup(func() { _ = lock.Close() })
+}
+
+func TestRunSecondScanFails(t *testing.T) {
+	// README §Database: while one scan holds the lock, a second scan
+	// fails at once, naming the lock file, without creating the
+	// database.
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	holdScanLock(t, path)
+
+	var stdout, stderr bytes.Buffer
+
+	code := run([]string{cmdScan, t.TempDir()}, &stdout, &stderr)
+	if code != exitFatal {
+		t.Errorf("run(scan) = %d, want %d", code, exitFatal)
+	}
+
+	want := "sfdupes: another scan is running (lock held on " +
+		path + ".lock)\n"
+	if got := stderr.String(); got != want {
+		t.Errorf("stderr = %q, want %q", got, want)
+	}
+
+	if got := stdout.String(); got != "" {
+		t.Errorf("stdout = %q, want nothing (data only)", got)
+	}
+
+	_, err := os.Stat(path)
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("stat %s = %v, want the database not created", path, err)
+	}
+}
+
+func TestRunScanReleasesLock(t *testing.T) {
+	// README §Database: a scan releases the lock however it ends.
+	t.Run("success", func(t *testing.T) {
+		path := testDBPath(t)
+		t.Setenv(databaseEnv, path)
+
+		scanFixture(t)
+		holdScanLock(t, path)
+	})
+
+	t.Run("fatal error", func(t *testing.T) {
+		path := brokenDatabase(t)
+		t.Setenv(databaseEnv, path)
+
+		code := run([]string{cmdScan, t.TempDir()}, io.Discard, io.Discard)
+		if code != exitFatal {
+			t.Fatalf("run(scan) = %d, want %d", code, exitFatal)
+		}
+
+		holdScanLock(t, path)
+	})
+}
+
+func TestRunReportsDuringScan(t *testing.T) {
+	// README §Database: report and trees never take the lock, so they
+	// run while a scan holds it.
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	scanFixture(t)
+	holdScanLock(t, path)
+
+	for _, name := range []string{cmdReport, cmdTrees} {
+		var stderr bytes.Buffer
+
+		code := run([]string{name}, io.Discard, &stderr)
+		if code != exitOK {
+			t.Errorf("run(%s) = %d, want %d; stderr: %s",
+				name, code, exitOK, stderr.String())
+		}
+	}
+}
+
+func TestRunStdoutClosedIsFatal(t *testing.T) {
+	// README §Error handling: a stdout write failure exits 1, reported
+	// in one line on stderr.
+	for _, name := range []string{cmdReport, cmdTrees} {
+		t.Run(name, func(t *testing.T) {
+			t.Setenv(databaseEnv, testDBPath(t))
+
+			scanFixture(t)
+
+			stdout, err := os.Create(filepath.Join(t.TempDir(), "stdout"))
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = stdout.Close()
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			var stderr bytes.Buffer
+
+			code := run([]string{name}, stdout, &stderr)
+			if code != exitFatal {
+				t.Errorf("run(%s) = %d, want %d", name, code, exitFatal)
+			}
+
+			got := stderr.String()
+			if !strings.HasPrefix(got, "sfdupes: write stdout: ") ||
+				!strings.Contains(got, os.ErrClosed.Error()) ||
+				strings.Count(got, "\n") != 1 {
+				t.Errorf("stderr = %q, want one line reporting the "+
+					"failed stdout write", got)
+			}
+		})
+	}
+}
+
+// errWriteFailed is the error failingWriter returns.
+var errWriteFailed = errors.New("write failed")
+
+// failingWriter is a stdout that fails every write.
+type failingWriter struct{}
+
+func (failingWriter) Write([]byte) (int, error) { return 0, errWriteFailed }
+
+func TestStdoutWriteErrorPropagates(t *testing.T) {
+	t.Setenv(databaseEnv, testDBPath(t))
+
+	scanFixture(t)
+
+	cases := map[string]func(context.Context, io.Writer) error{
+		cmdReport: runReport,
+		cmdTrees:  runTrees,
+	}
+
+	for name, fn := range cases {
+		err := fn(t.Context(), failingWriter{})
+		if !errors.Is(err, errWriteFailed) {
+			t.Errorf("%s: error = %v, want %v", name, err, errWriteFailed)
+		}
+	}
+}

progress.go

@@ -106,6 +106,8 @@ func (p *progress) increment() {
 }
 
 // warnf prints a one-line warning to stderr without corrupting the bar.
+// 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
@@ -115,7 +117,7 @@ func (p *progress) warnf(format string, args ...any) {
 		_ = p.bar.Clear()
 	}
 
-	fmt.Fprintf(os.Stderr, format+"\n", args...)
+	fmt.Fprintln(os.Stderr, escapePath(fmt.Sprintf(format, args...)))
 }
 
 // finish terminates the pass's display.

report.go

@@ -4,6 +4,7 @@ import (
 	"bufio"
 	"context"
 	"fmt"
+	"io"
 	"os"
 	"slices"
 	"strings"
@@ -31,9 +32,9 @@ 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. 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.
+// exiting, so that the deferred close always runs; the database is
+// closed before the caller formats its output, so it stays closed even
+// if that output fails.
 func loadRecords(ctx context.Context) ([]scanRec, error) {
 	dbPath := databasePath()
 
@@ -65,7 +66,7 @@ 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(ctx context.Context) error {
+func runReport(ctx context.Context, stdout io.Writer) error {
 	recs, err := loadRecords(ctx)
 	if err != nil {
 		return err
@@ -73,7 +74,7 @@ func runReport(ctx context.Context) error {
 
 	dupes := collectDupeGroups(recs)
 
-	out := bufio.NewWriterSize(os.Stdout, ioBufSize)
+	out := bufio.NewWriterSize(stdout, ioBufSize)
 
 	_, err = fmt.Fprintln(out, "first\tdupe\tsize")
 	if err != nil {
@@ -87,7 +88,7 @@ func runReport(ctx context.Context) error {
 	for _, g := range dupes {
 		for _, p := range g.paths[1:] {
 			_, err = fmt.Fprintf(out, "%s\t%s\t%d\n",
-				g.paths[0], p, g.size)
+				escapePath(g.paths[0]), escapePath(p), g.size)
 			if err != nil {
 				return fmt.Errorf("write stdout: %w", err)
 			}
@@ -156,6 +157,21 @@ func collectDupeGroups(recs []scanRec) []dupeGroup {
 	return dupes
 }
 
+// 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

report_test.go

@@ -1,10 +1,126 @@
 package main
 
 import (
+	"bytes"
+	"io"
+	"os"
+	"path/filepath"
 	"slices"
 	"testing"
 )
 
+// awkwardDir is a directory name holding every byte the reports escape.
+const awkwardDir = "/d/\tone\ntwo\rthree\\four"
+
+// 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 {
+	return []scanRec{
+		{size: 5, head: "h", tail: "t", content: "c", path: "/d/A/f"},
+		{size: 5, head: "h", tail: "t", content: "c", path: awkwardDir + "/f"},
+	}
+}
+
+// seedDatabase writes recs into a fresh database 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)
+	}
+
+	err = db.Close()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return path
+}
+
+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 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 TestCollectDupeGroups(t *testing.T) {
 	t.Parallel()
 

scan.go

@@ -85,10 +85,13 @@ type fileMeta struct {
 // least one other file shares are ever hashed: a size-unique file
 // cannot be a duplicate. A file of headTailMin or more gets its content
 // hash only when its size, head, and tail match another file's. Flag
-// parsing and the at-least-one-operand check are done by cobra. Errors
-// are returned rather than exiting, so that the deferred close — which
-// checkpoints the SQLite WAL — always runs. Cancelling ctx unwinds the
-// worker pools and aborts the scan with the context's error.
+// parsing and the at-least-one-operand check are done by cobra. The
+// scan holds the lock on the database for its whole run, so a second
+// scan fails before it walks the filesystem or opens the database.
+// Errors are returned rather than exiting, so that the deferred close —
+// which takes the database out of WAL mode — always runs, and the lock
+// is released after it. Cancelling ctx unwinds the worker pools and
+// aborts the scan with the context's error.
 func runScan(ctx context.Context, roots []string, workers int,
 	oneFS bool,
 ) error {
@@ -103,12 +106,19 @@ func runScan(ctx context.Context, roots []string, workers int,
 
 	dbPath := databasePath()
 
+	lock, err := lockScanDatabase(dbPath)
+	if err != nil {
+		return err
+	}
+
+	defer func() { _ = lock.Close() }()
+
 	db, err := openScanDatabase(ctx, dbPath)
 	if err != nil {
 		return err
 	}
 
-	defer func() { _ = db.Close() }()
+	defer closeScanDatabase(ctx, db, dbPath)
 
 	st, err := syncScan(ctx, db, roots, workers, oneFS)
 	if err != nil {

scan_test.go

@@ -7,6 +7,7 @@ import (
 	"database/sql"
 	"encoding/hex"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"runtime"
@@ -1548,7 +1549,7 @@ func TestScanHashWriteFailureUnwindsPool(t *testing.T) {
 
 	code := run([]string{
 		cmdScan, "--workers", strconv.Itoa(hashLeakWorkers), dir,
-	}, &stderr)
+	}, io.Discard, &stderr)
 	if code != exitFatal {
 		t.Fatalf("run(scan) = %d, want %d; stderr: %s",
 			code, exitFatal, stderr.String())

trees.go

@@ -5,6 +5,7 @@ import (
 	"context"
 	"crypto/sha256"
 	"fmt"
+	"io"
 	"os"
 	"slices"
 	"strconv"
@@ -36,7 +37,7 @@ 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(ctx context.Context) error {
+func runTrees(ctx context.Context, stdout io.Writer) error {
 	recs, err := loadRecords(ctx)
 	if err != nil {
 		return err
@@ -47,7 +48,7 @@ func runTrees(ctx context.Context) error {
 
 	dupes := collectTreeGroups(allDirs, super)
 
-	out := bufio.NewWriterSize(os.Stdout, ioBufSize)
+	out := bufio.NewWriterSize(stdout, ioBufSize)
 
 	_, err = fmt.Fprintln(out, "first\tdupe\tfiles\tsize")
 	if err != nil {
@@ -62,7 +63,8 @@ func runTrees(ctx context.Context) error {
 		first := g[0]
 		for _, n := range g[1:] {
 			_, err = fmt.Fprintf(out, "%s\t%s\t%d\t%d\n",
-				first.path, n.path, first.fileCount, first.totalSize)
+				escapePath(first.path), escapePath(n.path),
+				first.fileCount, first.totalSize)
 			if err != nil {
 				return fmt.Errorf("write stdout: %w", err)
 			}
@@ -87,8 +89,8 @@ func runTrees(ctx context.Context) error {
 
 // buildHierarchy reconstructs the directory hierarchy from the record
 // paths under a synthetic super-root. Paths are split on "/"; for
-// absolute paths the first component is empty, which simply becomes a
-// top-level node representing "/". It returns the super-root and every
+// absolute paths the first component is empty, which becomes the
+// top-level node with path "/". It returns the super-root and every
 // directory node created.
 func buildHierarchy(recs []scanRec) (*treeNode, []*treeNode) {
 	super := &treeNode{}
@@ -102,9 +104,17 @@ func buildHierarchy(recs []scanRec) (*treeNode, []*treeNode) {
 		for _, c := range comps[:len(comps)-1] {
 			child := node.dirs[c]
 			if child == nil {
-				childPath := c
-				if node != super {
-					childPath = node.path + "/" + c
+				childPath := node.path + "/" + c
+
+				// The root directory's path is "/", not empty, and its
+				// children's paths start with one slash, not two.
+				switch {
+				case node == super && c == "":
+					childPath = "/"
+				case node == super:
+					childPath = c
+				case node.path == "/":
+					childPath = "/" + c
 				}
 
 				child = &treeNode{path: childPath, parent: node}

trees_test.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"bytes"
 	"slices"
 	"testing"
 )
@@ -84,6 +85,44 @@ func TestBuildHierarchyCounts(t *testing.T) {
 	}
 }
 
+func TestBuildHierarchyRootPath(t *testing.T) {
+	t.Parallel()
+
+	// The root directory's path is "/", never empty, and its
+	// children's paths start with a single slash.
+	_, dirs := buildHierarchy([]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 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\n" +
+		`/d/\tone\ntwo\rthree\\four` + "\t/d/A\t1\t5\n"
+	if got := stdout.String(); got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+}
+
 func TestTreeDigests(t *testing.T) {
 	t.Parallel()