trees: count a nested dupe tree once in the reclaimable total (closes #168)

The total summed `size` over every row. It now leaves out a row whose
`dupe` lies inside another row's `dupe`. Before, such a row's bytes were
counted again in each row whose `dupe` holds it. The rows are unchanged.
README defines the total to match.

Model: opus-5-5

README.md

@@ -21,7 +21,7 @@ file takes too long. It has five subcommands. `scan` walks the filesystem and
 records the files it finds in an SQLite database. SQLite keeps a whole database
 in one file. The database is kept between runs. A rescan reads only new and
 changed files. That makes `scan` cheap enough to run every day from `cron`, the
-system's job scheduler. `report`, `trees` and `info` read the database alone and
+system's job scheduler. `report`, `trees` and `info` work from the database and
 can run at any time. `dwim` scans `/` and then prints the `trees` report, for a
 first look at a new machine with one command.
 
@@ -98,13 +98,15 @@ Each `-v` flag below makes a bind mount, which shows a host directory at a path
 inside the container. Bind-mount `/var/lib/sfdupes` to keep the database between
 runs. Mount the tree to scan at the same path inside the container as on the
 host. Read-only access is enough. The database then records the host's paths,
-and so do the reports.
+and so do the reports. `report` and `trees` need that mount too. Without it,
+every recorded path counts as gone, and each report holds only its header line.
 
 ```sh
 make docker
 docker run --rm -v /srv:/srv:ro -v /var/lib/sfdupes:/var/lib/sfdupes \
     sfdupes scan /srv
-docker run --rm -v /var/lib/sfdupes:/var/lib/sfdupes sfdupes report > dupes.tsv
+docker run --rm -v /srv:/srv:ro -v /var/lib/sfdupes:/var/lib/sfdupes \
+    sfdupes report > dupes.tsv
 ```
 
 ### Daily scan from `cron`
@@ -159,8 +161,10 @@ to keep is your choice.
 
 A row is a candidate, not proof:
 
-- The reports show each file as it was when a scan last recorded it. A file may
+- The reports show each file as it was when a scan last recorded it. They check
-  have changed or gone since.
+  only that each copy still exists: the file, or the directory at the top of a
+  tree. A file may have changed since, and a file inside a tree may be gone. Run
+  `scan` again to bring the reports up to date.
 - A file of 100 MiB or more is compared only on samples of its content (see
   "Duplicate detection").
 - Two paths that are hard links, two names for one file, are listed as
@@ -208,8 +212,9 @@ makes the comparison exact. Reading samples cuts a 150 GiB file to about 150 MiB
 of reads, at the price of a comparison that is not exact.
 
 The hashes live in a database that is kept between runs. A rescan reads only new
-files, and files whose size changed or whose modification time (mtime) is newer
+files, and files whose size or modification time (mtime) differs from their
-than recorded. All analysis then works from the database alone.
+record. All analysis then works from the database. The reports only check that
+each copy they name still exists.
 
 The goal is whole duplicated trees, not only single files. A download extracted
 twice, or a project copied once too often, is such a tree. It can be removed as
@@ -235,9 +240,10 @@ In order:
    the files of the directories it is reading.
 3. **Rescan cheaply, analyze from the database.** The scan keeps its database
    between runs, and an unchanged file is never read again. `report`, `trees`
-   and `info` work from the database alone and never touch the scanned
+   and `info` work from the database and never read a scanned file. `report` and
-   filesystem. `scan` is built to run from `cron`. The reports run at any time,
+   `trees` check only that each copy they name still exists, and leave out a
-   against what the database holds.
+   copy that is gone. `scan` is built to run from `cron`. The reports run at any
+   time, against what the database holds.
 4. **Keep the streams apart.** Everything on stdout is machine-readable data.
    Everything for a human reader, such as progress and warnings, goes to stderr.
 
@@ -248,15 +254,14 @@ In order:
 - `report` prints the file-level duplicate report from the database.
 - `trees` prints the duplicate-tree report from the database.
 - `info` prints the database's details.
-- `dwim` scans `/` with the default excludes, then prints the duplicate-tree
+- `dwim` scans `/`, then prints the duplicate-tree report.
-  report.
 
 ```
-sfdupes scan [--workers N] [-x] [--no-default-excludes] PATH...
+sfdupes scan [--workers N] [-x] [--no-default-excludes] [--exclude PATH]... PATH...
 sfdupes report > dupes.tsv
 sfdupes trees > dupetrees.tsv
 sfdupes info
-sfdupes dwim
+sfdupes dwim [--workers N] [-x] [--no-default-excludes] [--exclude PATH]...
 sfdupes --version
 sfdupes [command] --help
 ```
@@ -286,22 +291,34 @@ The reference below is also the program's specification.
   database is `/var/lib/sfdupes/db.sqlite`. There is no command-line flag for
   it. The path names the file exactly, whatever characters it holds. A relative
   path is relative to the working directory.
-- `--workers N` (`scan`) sets how many directories `scan` reads at once while it
+- `--workers N` (`scan`, `dwim`) sets how many directories `scan` reads at once
-  lists the trees. It also sets how many files `scan` reads at once while it
+  while it lists the trees. It also sets how many files `scan` reads at once
-  hashes them. The default is the number of CPUs. `N` must be at least 1. A
+  while it hashes them. The default is the number of CPUs. `N` must be at
-  smaller value is a usage error, reported in one line on stderr with exit 2
+  least 1. A smaller value is a usage error, reported in one line on stderr with
-  before anything is scanned.
+  exit 2 before anything is scanned.
-- `-x`, `--one-file-system` (`scan`) keeps the walk of each operand out of
+- `-x`, `--one-file-system` (`scan`, `dwim`) keeps the walk of each operand out
-  directories on other filesystems, as the same flag does for `du` and `rsync`.
+  of directories on other filesystems, as the same flag does for `du` and
-  By default the walk also enters directories on other filesystems.
+  `rsync`. By default the walk also enters directories on other filesystems.
-- `--no-default-excludes` (`scan`) lets the walk enter the default excludes.
+- `--no-default-excludes` (`scan`, `dwim`) lets the walk enter the default
-  Those are the system and temporary directories the walk otherwise leaves out,
+  excludes. Those are the system and temporary directories the walk otherwise
-  such as `/var/tmp` on Linux (see "Rules for the walk").
+  leaves out, such as `/var/tmp` on Linux (see "Rules for the walk").
+- `--exclude PATH` (`scan`, `dwim`) keeps the walk out of `PATH` and everything
+  below it. `PATH` may be a directory or a file. The flag may be given more than
+  once. The walk knows `PATH` by its device ID and inode number, as it knows the
+  database files (see "Rules for the walk"). So the walk leaves `PATH` out
+  whatever path leads to it. That includes a hard link to a file given as
+  `PATH`. A symlink given as `PATH` excludes its target. An empty `PATH`, as in
+  `--exclude ""`, is a usage error, reported in one line on stderr with exit 2
+  before anything is scanned. A `PATH` that does not exist, or whose real path
+  `scan` cannot find, is a fatal error. So is an operand at or below one (see
+  "Operands").
 - `--version`, `-v` prints `sfdupes VERSION` (see "Install") to stdout and
   exits 0. It writes nothing to stderr.
 - `--help`, `-h`, alone or after a subcommand, prints the help text to stderr
-  and exits 0. It writes nothing to stdout. `sfdupes scan --help` also lists the
+  and exits 0. It writes nothing to stdout. The help of `sfdupes` and of `scan`
-  default excludes of the system it runs on, and the filesystem types the walk
+  names the database. The help of `report`, `trees`, `info` and `dwim` says what
+  each prints. `sfdupes scan --help` and `sfdupes dwim --help` also list the
+  default excludes of the system they run on, and the filesystem types the walk
   never records anything on.
 
 ### Duplicate detection
@@ -355,6 +372,10 @@ default. An operand may be a directory or a regular file.
 - An operand that does not exist is a fatal error, and so is a symlink whose
   target does not exist. `scan` then stops before it walks anything, and exits
   with code 1.
+- An operand at or below an `--exclude` path is a fatal error too. The message
+  names the operand and the `--exclude` path. `scan` compares the operand and
+  each directory above it with the `--exclude` paths by device ID and inode
+  number, not by name.
 - Each operand is resolved to its real path before the walk, as `realpath`
   prints it. A relative operand is joined to the working directory as `pwd -P`
   prints it. Every symlink in the path is then followed. A `..` after a symlink
@@ -410,17 +431,16 @@ operands:
 
 - A file not yet in the database is hashed and inserted.
 - A file already in the database is not read again when its size and mtime match
-  its record. The mtime matches when it is not newer than the recorded one. This
+  its record. This is what makes a daily rescan cheap.
-  is what makes a daily rescan cheap.
 - When such a file's size on disk differs from its recorded `disk_size`, `scan`
   updates `disk_size` alone. It still does not read the file, and counts it as
   unchanged. ZFS, for example, counts a new file's blocks up to seconds after
   the write. A block is the unit in which a filesystem allocates disk space. A
   file scanned within those seconds gets its real `disk_size` at the next scan.
-- `scan` hashes a file again when its size differs or its mtime is newer. The
+- `scan` hashes a file again when its size or its mtime differs from its record.
-  mtime is compared to the nanosecond, as finely as the filesystem records it. A
+  An older mtime counts as much as a newer one. A file put back by `cp -p`,
-  same-size rewrite counts as a change whenever the filesystem gives it a later
+  `rsync -a` or a restore from backup often has an older mtime. The mtime is
-  mtime, even within the same second.
+  compared to the nanosecond, as finely as the filesystem records it.
 - The scan deletes each record under a scanned operand whose file it could not
   verify. That covers deleted files, and paths the scan could not stat or read
   this run. To stat a file is to read its details, such as its size, without
@@ -431,15 +451,16 @@ operands:
   scanned on different schedules into one database.
 - The scan keeps every record at or below a path that the walk leaves out for
   one of these reasons:
+    - it is an `--exclude` path;
     - it is a default exclude;
     - it is not on a persistent filesystem;
     - with `-x`, it is a directory on another filesystem than its operand.
 
     Such records count as outside the scanned operands. So with `-x`, a
     filesystem mounted under an operand can be scanned on its own schedule into
-    the same database. An operand may itself lie at or inside such a path, as
+    the same database. An operand may itself lie at or inside such a path, other
-    "Operands" describes. Its walk verifies the records below it, so they are
+    than an `--exclude` path (see "Operands"). Its walk verifies the records
-    deleted when their files are gone.
+    below it, so they are deleted when their files are gone.
 
 #### Phases
 
@@ -538,6 +559,17 @@ walk practical on large or busy storage pools.
     The path is not counted as skipped. The records below it are kept, as
     described under "What a scan does to the database".
 
+- The walk never enters or records an `--exclude` path, nor anything below it.
+  For each one it reaches, `scan` prints a line on stderr naming it:
+
+    ```
+    scan: skipped /srv/cache (--exclude)
+    ```
+
+    The path is not counted as skipped. The scan keeps the records at and below
+    it, as described under "What a scan does to the database".
+    `--no-default-excludes` does not change this rule.
+
 - Below an operand, the walk does not enter a default exclude. On Linux, the
   default excludes hold temporary files and the kernel's view of the running
   system. They depend on the system, and `sfdupes scan --help` lists those of
@@ -612,7 +644,8 @@ from a thread of its own and never blocks the workers.
   it repeats another or lies under another;
 - the progress display of each phase (see "Progress"). `scan` prints each
   warning for a skipped path as it happens. It prints a line the same way for
-  each path left out as a default exclude or as not on a persistent filesystem;
+  each path left out as an `--exclude` path, as a default exclude or as not on a
+  persistent filesystem;
 - the summary line;
 - a warning when a report still has the database open as the scan ends (see
   "Concurrent reads").
@@ -655,20 +688,29 @@ and `scan` leaves it ignored.
 
 `report` reads every record from the database. It takes no positional arguments.
 A positional argument is anything on the command line that is not a flag, such
-as the paths `scan` takes. `report` never touches the scanned filesystem. It
+as the paths `scan` takes. `report` never opens a scanned file. It checks that
-neither stats nor opens any path in the records. It reads the database and
+each path in a group still exists, and looks at no other path. The check is
-writes to stdout and stderr, and nothing else. Its output is the same whether or
+`lstat`, the system call that looks up a path without following a symlink:
-not the scanned filesystem is still mounted.
+
+- A path is gone when `lstat` finds that it, or a directory above it, does not
+  exist.
+- Any other error, such as a permission error, counts as present. So a user who
+  may not look inside a directory still sees its copies.
+
+The check does not notice a file that changed after the scan. Run `scan` again
+to bring the report up to date.
 
 Processing:
 
 - Records are grouped by signature, the four values
   `(size, head, tail, content)`.
-- Every group with two or more paths is a duplicate group.
+- In a group with two or more paths, a path that is gone is left out. A group
+  that still has two or more paths is a duplicate group.
+- Empty files form no group, because removing one frees nothing.
 - Within a group, paths are sorted in byte order. The first is `first`, and
   every other path is a `dupe`.
 - Groups are ordered by size, largest first, then by `first` path. The output is
-  the same for the same database contents.
+  the same for the same database contents and the same paths on disk.
 
 `report` has two phases, each with its own progress display on stderr (see
 "Progress"). `open` opens the database. `read` gets the number of records from
@@ -713,7 +755,7 @@ The summary line on stderr gives:
 - the reclaimable bytes, the sum of `size` over all rows.
 
 ```
-report: 14 records read, 5 duplicate groups, 8 dupe files, 10.0 KiB reclaimable
+report: 14 records read, 4 duplicate groups, 7 dupe files, 10.0 KiB reclaimable
 ```
 
 ### `trees` mode
@@ -721,8 +763,9 @@ report: 14 records read, 5 duplicate groups, 8 dupe files, 10.0 KiB reclaimable
 `trees` reads the same database as `report` and takes no positional arguments.
 It reports whole duplicate directory trees. Two directories are duplicate trees
 when they hold the same relative paths, and each path holds a file with the same
-signature in both. Like `report`, it never touches the scanned filesystem. It
+signature in both. It rebuilds the directory tree from the paths in the records,
-rebuilds the directory tree from the paths in the records, split on `/`.
+split on `/`. Like `report`, it never opens a scanned file. It checks only that
+the directory at the top of each copy still exists, as `report` checks a path.
 
 Definitions:
 
@@ -741,15 +784,21 @@ Processing:
 - `trees` builds the directory tree and computes every directory's digest. It
   then groups the directories by digest. Every group with two or more
   directories is a duplicate-tree group.
+- `trees` leaves out a group whose trees hold 0 bytes, because removing one
+  frees nothing. An empty file still counts toward the digest of a tree that
+  holds other files.
 - `trees` leaves out a group that a group of its members' parents already
   implies. A group is left out when its members' parents are distinct
   directories that all have the same digest. The parents' group, or an
   ancestor's, already implies it. A group is always reported when it holds
   sibling directories, or when its members' parents have different digests.
+- A directory that is gone is dropped from its group. A group left with fewer
+  than two directories is not reported.
 - Within a group, paths are sorted in byte order. The first is `first`, and
   every other path is a `dupe`.
 - Groups are ordered by total tree size, largest first, then by `first` path.
-  The output is the same for the same database contents.
+  The output is the same for the same database contents and the same paths on
+  disk.
 
 Two limitations are accepted:
 
@@ -763,8 +812,9 @@ Two limitations are accepted:
 `trees` has four phases, each with its own progress display on stderr (see
 "Progress"). `open` opens the database. `read` gets the number of records from
 the `totals` table, then reads them in path order. It builds the directory tree
-and computes the digests as it goes. `group` groups the directories by digest
+and computes the digests as it goes. `group` groups the directories by digest,
-and picks the groups to report. `write` writes them to stdout.
+picks the groups to report and checks that their directories still exist.
+`write` writes the groups to stdout.
 
 #### Trees output format
 
@@ -798,7 +848,8 @@ The summary line on stderr gives:
 - the records read;
 - the duplicate-tree groups;
 - the dupe trees, which is the number of rows;
-- the reclaimable bytes, the sum of `size` over all rows.
+- the reclaimable bytes, the sum of `size` over all rows, leaving out a row
+  whose `dupe` lies inside another row's `dupe`.
 
 ```
 trees: 14 records read, 1 duplicate tree groups, 1 dupe trees, 3.0 KiB reclaimable
@@ -807,14 +858,25 @@ trees: 14 records read, 1 duplicate tree groups, 1 dupe trees, 3.0 KiB reclaimab
 ### `dwim` mode
 
 `dwim`, short for "do what I mean", scans a new machine and reports its
-duplicate trees in one command. It takes no positional arguments and no flags of
+duplicate trees in one command. It takes no positional arguments. Like `scan`,
-its own. Like `scan`, it should run as root, so that it can read every file.
+it should run as root, so that it can read every file.
 
-`dwim` runs what `sfdupes scan /` runs with no flags. The walk skips the default
+`dwim` takes these flags of `scan`, with the same meaning (see "Settings"):
-excludes and crosses into other filesystems. `--workers` keeps its default. The
+
+- `--workers N`;
+- `-x`, `--one-file-system`;
+- `--no-default-excludes`;
+- `--exclude PATH`, which may be given more than once.
+
+`dwim` runs what `sfdupes scan /` runs with the same flags. With no flags, the
+walk skips the default excludes and crosses into other filesystems. The
 database, its creation and the scan lock are those of `scan`. Then `dwim` runs
 what `sfdupes trees` runs. The largest trees come first.
 
+```
+sfdupes dwim -x --exclude /srv/cache
+```
+
 The report goes to stdout, exactly as `trees` prints it. On stderr comes what
 `scan` prints, then what `trees` prints, then one last line:
 
@@ -822,8 +884,8 @@ The report goes to stdout, exactly as `trees` prints it. On stderr comes what
 dwim: run "sfdupes trees" to print this report again
 ```
 
-The database keeps the scan, so `sfdupes trees` prints the same report later,
+The database keeps the scan, so `sfdupes trees` prints the report again later,
-even after the terminal is gone.
+even after the terminal is gone. It then leaves out a copy deleted in between.
 
 `SIGINT` or `SIGTERM` stops the scan as it stops `scan` (see "Stopping a scan").
 `dwim` then prints no report and exits 1. A fatal scan error also ends it before
@@ -1115,9 +1177,10 @@ in, and a phase that may wait in two places names both, as `disk/db`:
 - `hash` says `disk/db`, because it reads files and writes their records to the
   database between them.
 - `load`, `update` and the `read` phase of `trees` say `db`.
-- The `read` phase of `report` says `db/out`, because it writes the report to
+- The `read` phase of `report` says `db/disk/out`. It checks that the paths of
-  stdout while it reads.
+  each group still exist, and writes the report to stdout, while it reads.
-- `group` of `trees` says `cpu`, for work in memory, and its `write` says `out`.
+- `group` of `trees` says `cpu/disk`, for work in memory and the check that each
+  copy still exists. Its `write` says `out`.
 - A phase still waiting for its total says what it waits for, and nothing more.
 
 On a terminal:
@@ -1175,6 +1238,9 @@ showing the count it stopped at.
 - `1`: a fatal error, a `scan` stopped by `SIGINT` or `SIGTERM`, or a `dwim`
   stopped by either during its scan. A fatal error is one of these:
     - an operand that does not exist, or whose real path `scan` cannot find;
+    - an `--exclude` path that does not exist, or whose real path `scan` cannot
+      find;
+    - an operand at or below an `--exclude` path;
     - a list of mounted filesystems that `scan` cannot read;
     - another `scan` holding the lock (see "The scan lock");
     - a database, its directory or its lock file that cannot be created or
@@ -1194,6 +1260,7 @@ showing the count it stopped at.
       `--workers abc`;
     - `scan` with no operand;
     - `--workers` below 1;
+    - an empty `--exclude` value, as in `--exclude ""`;
     - `report`, `trees`, `info` or `dwim` with a positional argument.
 
 A fatal error is reported on stderr, starting with `sfdupes:`. A failed write to
@@ -1357,8 +1424,8 @@ commands of their own:
   not a goal. `modernc.org/sqlite` is pure Go too, so the binary builds without
   cgo. The `Makefile` exports `CGO_ENABLED=0`. The test build is the one
   exception, because the race detector needs cgo (see `script/test`).
-- `report` and `trees` give the same output for the same database contents,
+- `report` and `trees` give the same output for the same database contents and
-  whatever order the records were inserted in.
+  the same paths on disk, whatever order the records were inserted in.
 
 ### Definition of done
 
@@ -1382,7 +1449,7 @@ All of the following, run in this directory, must pass:
     head -c 2000 /dev/urandom > "$d/a/unique.bin"     # same size, different content
     printf 'x' > "$d/tiny1"; printf 'x' > "$d/tiny2"  # 1-byte duplicates
     printf 'y' > "$d/tiny3"                           # 1-byte non-duplicate
-    : > "$d/empty1"; : > "$d/empty2"                  # empty duplicates
+    : > "$d/empty1"; : > "$d/empty2"                  # empty files
     # duplicate trees: t1 and t2 are identical; t3 differs by one filename
     mkdir -p "$d/t1/sub" "$d/t2/sub" "$d/t3/sub"
     head -c 3000 /dev/urandom > "$d/t1/f1"
@@ -1407,8 +1474,8 @@ All of the following, run in this directory, must pass:
       is the path that sorts first.
     - `t1/f1`, `t2/f1` and `t3/f1` form one group.
     - `t1/sub/f2`, `t2/sub/f2` and `t3/sub/f2renamed` form one group.
-    - `tiny1` and `tiny2` form a pair, and so do `empty1` and `empty2`.
+    - `tiny1` and `tiny2` form a pair.
-    - `unique.bin` and `tiny3` appear nowhere.
+    - `unique.bin`, `tiny3`, `empty1` and `empty2` appear nowhere.
     - The groups come in order of size, largest first.
 
     `trees` prints exactly one row, `$d/t1` as `first` and `$d/t2` as `dupe`.
@@ -1423,7 +1490,7 @@ All of the following, run in this directory, must pass:
 
     The test suite automates this scenario (see
     `internal/sfdupes/scan_test.go`). It also checks that `report` and `trees`
-    never touch the scanned filesystem.
+    leave out a copy removed after the scan.
 
 ## TODO
 

TODO.md

@@ -29,6 +29,36 @@
 Newest first. An entry ends with its date and its issue or branch, where those
 are known.
 
+- The reclaimable total of `trees` is the sum of `size` over all rows, leaving
+  out a row whose `dupe` lies inside another row's `dupe`. Before, such a row's
+  bytes were counted again in each row whose `dupe` holds it (2026-11-11,
+  https://git.eeqj.de/sneak/sfdupes/issues/168)
+- `dwim` takes the `scan` flags `--workers`, `-x`, `--no-default-excludes` and
+  `--exclude`, with the same meaning. Both commands register and check them with
+  the same code (2026-11-11, https://git.eeqj.de/sneak/sfdupes/issues/162)
+
+- The help of `sfdupes` and of `scan` names the database, its default path and
+  `SFDUPES_DATABASE`. The help of `report` and `trees` lists the columns, the
+  order of the rows and the escapes. The help of `info` lists its lines. The
+  help of `dwim` says that it scans `/`, should run as root and keeps the scan
+  in the database (2026-11-11, https://git.eeqj.de/sneak/sfdupes/issues/177)
+- New `scan` flag `--exclude PATH`, which may be repeated. The walk neither
+  enters nor records an excluded path, and keeps the records below it. An
+  operand at or below one is a fatal error (2026-11-11,
+  https://git.eeqj.de/sneak/sfdupes/issues/163)
+
+- `report` and `trees` leave out a copy that was deleted after the scan. Each
+  checks only the copy itself with `lstat`: the file, or the directory at the
+  top of a tree. A group left with one copy is not reported. A missing `scan`
+  operand is still a fatal error (2026-11-11,
+  https://git.eeqj.de/sneak/sfdupes/issues/173)
+- The usage line of `scan` no longer ends in `[flags]`. It is the line
+  `README.md` shows under "Subcommands" (2026-11-11,
+  https://git.eeqj.de/sneak/sfdupes/issues/169)
+- `report` and `trees` leave out empty files. `report` writes no group of size
+  0, and `trees` writes no group whose trees hold 0 bytes. An empty file still
+  counts toward a tree's digest (2026-11-11,
+  https://git.eeqj.de/sneak/sfdupes/issues/178)
 - The Go code moved out of the repository root. `cmd/sfdupes/main.go` is the
   command, and it calls `Main` in the package `internal/sfdupes`. `main.go`
   became `internal/sfdupes/cli.go`. Every other file kept its name. The install

internal/sfdupes/cancel_test.go

@@ -358,8 +358,9 @@ func TestRunScanInterrupted(t *testing.T) {
 	stderr := captureStderr(t)
 	dir := buildSmokeTree(t)
 
-	err := runScan(t.Context(), []string{dir}, walkCancelWorkers, false,
+	opts := scanOptions{workers: walkCancelWorkers}
-		false)
+
+	err := runScan(t.Context(), []string{dir}, opts)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -382,8 +383,7 @@ func TestRunScanInterrupted(t *testing.T) {
 	go func() {
 		defer close(done)
 
-		err = runScan(cancelledContext(t), []string{dir}, walkCancelWorkers,
+		err = runScan(cancelledContext(t), []string{dir}, opts)
-			false, false)
 	}()
 
 	awaitReturn(t, done, "runScan")
@@ -410,8 +410,7 @@ func TestRunScanInterrupted(t *testing.T) {
 			got, before)
 	}
 
-	err = runScan(t.Context(), []string{dir}, walkCancelWorkers, false,
+	err = runScan(t.Context(), []string{dir}, opts)
-		false)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -437,7 +436,7 @@ func TestRunScanInterruptedMidHash(t *testing.T) {
 	dir := buildWalkCancelTree(t)
 
 	err := runScan(newWalkClock(hashCancelAtDone), []string{dir},
-		walkCancelWorkers, false, false)
+		scanOptions{workers: walkCancelWorkers})
 	if !errors.Is(err, errInterrupted) {
 		t.Fatalf("runScan interrupted mid-hash = %v, want %v",
 			err, errInterrupted)

internal/sfdupes/cli.go

@@ -10,6 +10,7 @@ import (
 	"os"
 	"runtime"
 	"runtime/debug"
+	"slices"
 
 	"github.com/spf13/cobra"
 )
@@ -31,15 +32,82 @@ const (
 	cmdDwim   = "dwim"
 )
 
+// databaseHelp is the paragraph of the root and scan help that names
+// the database (README "Location").
+const databaseHelp = "scan and dwim store what they find in a database " +
+	"file. report, trees\nand info read it. The file is $" + databaseEnv +
+	" when that is set and\nnot empty, and otherwise " +
+	defaultDatabasePath + ", where creating it\nneeds root.\n"
+
+// escapesHelp is the paragraph of the report and trees help on how
+// paths are escaped (README "Report output format").
+const escapesHelp = `Four characters in a path are escaped, so each row stays one line:
+
+  \\  a backslash
+  \t  a tab
+  \n  a newline
+  \r  a carriage return
+`
+
+// reportHelp, treesHelp, infoHelp and dwimHelp follow the one-line
+// summary in the help of their subcommands.
+const (
+	reportHelp = `The report is tab-separated text on stdout: a header line, then one
+row per duplicate file. The columns are:
+
+  first   the path that sorts first, byte by byte, in its group of copies
+  dupe    another copy of that file
+  size    the file's size in bytes
+
+Rows are ordered by size, largest first, then by path.
+
+` + escapesHelp
+
+	treesHelp = `The report is tab-separated text on stdout: a header line, then one
+row per duplicate directory tree. The columns are:
+
+  first      the path that sorts first, byte by byte, in its group of copies
+  dupe       another copy of that tree
+  files      the number of regular files in one copy
+  size       their total size in bytes
+  disk_size  the bytes the dupe copy takes on disk
+
+Rows are ordered by size, largest first, then by path.
+
+` + escapesHelp
+
+	infoHelp = `The details go to stdout, one per line. Each line holds a name and its
+value, separated by a tab:
+
+  database                the path, and where it came from
+  database file size      in bytes, then rounded, as 2147483648 (2.0 GiB)
+  -wal file size          in bytes, then rounded; only if a -wal file exists
+  modified                when the database file last changed, in UTC
+  schema version          the version of the database's layout
+  records                 the number of records
+  size of recorded files  their total size, in bytes, then rounded
+`
+
+	dwimHelp = `dwim runs what "sfdupes scan /" runs with the same flags, then what
+"sfdupes trees" runs. Run it as root, so that the scan can read every
+file. The scan is stored in the database, as scan stores it, so
+"sfdupes trees" prints the report again later.
+`
+)
+
 // 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
+// errWorkersBelowOne is the usage error for a --workers value below 1.
-// below 1.
 var errWorkersBelowOne = errors.New("--workers must be at least 1")
 
+// errEmptyExcludeValue is the usage error for an empty --exclude value,
+// as from --exclude "$DIR" with DIR unset. Taken as a path, it
+// would name the working directory.
+var errEmptyExcludeValue = errors.New("--exclude must not be empty")
+
 // 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.
@@ -187,62 +255,116 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 		}),
 	}
 
-	dwimCmd := &cobra.Command{
+	root.Long = root.Short + ".\n\n" + databaseHelp
-		Use:   cmdDwim,
+	reportCmd.Long = reportCmd.Short + ".\n\n" + reportHelp
-		Short: "Scan / with the default excludes, then print the duplicate-tree report",
+	treesCmd.Long = treesCmd.Short + ".\n\n" + treesHelp
-		Args:  cobra.NoArgs,
+	infoCmd.Long = infoCmd.Short + ".\n\n" + infoHelp
-		RunE: runE(func(ctx context.Context, _ []string) error {
-			return runDwim(ctx, "/", stdout)
-		}),
-	}
 
-	root.AddCommand(newScanCommand(), reportCmd, treesCmd, infoCmd, dwimCmd)
+	root.AddCommand(newScanCommand(), reportCmd, treesCmd, infoCmd,
+		newDwimCommand(stdout))
 
 	return root
 }
 
-// newScanCommand builds the scan subcommand, with its --workers, -x and
+// scanOptions holds the values of the flags that scan and dwim share:
-// --no-default-excludes flags. Its help lists the default excludes of
+// --workers, -x, --no-default-excludes and --exclude.
-// the system it runs on, and the filesystem types it never records
+type scanOptions struct {
-// anything on.
+	workers           int
+	oneFS             bool
+	noDefaultExcludes bool
+	excludePaths      []string
+}
+
+// scanFlagsUsage names the flags that scan and dwim share, for their
+// usage lines.
+const scanFlagsUsage = "[--workers N] [-x] [--no-default-excludes] " +
+	"[--exclude PATH]..."
+
+// addScanFlags adds the flags that scan and dwim share to cmd, which
+// stores their values in opts.
+func addScanFlags(cmd *cobra.Command, opts *scanOptions) {
+	cmd.Flags().IntVar(&opts.workers, "workers", runtime.NumCPU(),
+		"concurrent workers for the walk and hash phases")
+	cmd.Flags().BoolVarP(&opts.oneFS, "one-file-system", "x", false,
+		"do not cross filesystem boundaries")
+	cmd.Flags().BoolVar(&opts.noDefaultExcludes, "no-default-excludes",
+		false, "enter the default excludes, the paths listed above")
+	// A string array, not a slice, so a comma in a path is not a
+	// separator.
+	cmd.Flags().StringArrayVar(&opts.excludePaths, "exclude", nil,
+		"never enter or record `PATH` or anything below it; repeatable")
+}
+
+// check rejects the flag values that are usage errors, before the
+// command runs. It is the PreRunE of scan and dwim.
+func (o *scanOptions) check(cmd *cobra.Command, _ []string) error {
+	err := checkScanWorkers(cmd, o.workers)
+	if err != nil {
+		return err
+	}
+
+	return rejectEmptyExcludeValue(cmd, o.excludePaths)
+}
+
+// newScanCommand builds the scan subcommand. Its help names the
+// database, and lists the default excludes of the system it runs on and
+// the filesystem types it never records anything on.
 func newScanCommand() *cobra.Command {
-	var (
+	var opts scanOptions
-		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...",
+		Use: cmdScan + " " + scanFlagsUsage + " PATH...",
-		Short: short,
+		// The Use line already names every flag, so cobra must not
-		Long:  short + ".\n\n" + defaultExcludesHelp(runtime.GOOS),
+		// append its generic "[flags]" to it.
-		Args:  cobra.MinimumNArgs(1),
+		DisableFlagsInUseLine: true,
-		PreRunE: func(cmd *cobra.Command, _ []string) error {
+		Short:                 short,
-			return checkScanWorkers(cmd, scanWorkers)
+		Long: short + ".\n\n" + databaseHelp + "\n" +
-		},
+			defaultExcludesHelp(runtime.GOOS),
+		Args:    cobra.MinimumNArgs(1),
+		PreRunE: opts.check,
 		RunE: runE(func(ctx context.Context, args []string) error {
 			ctx, stop := interruptContext(ctx)
 			defer stop()
 
-			return runScan(ctx, args, scanWorkers, scanOneFS,
+			return runScan(ctx, args, opts)
-				scanNoDefaultExcludes)
 		}),
 	}
-	scanCmd.Flags().IntVar(&scanWorkers, "workers", runtime.NumCPU(),
+	addScanFlags(scanCmd, &opts)
-		"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
+// newDwimCommand builds the dwim subcommand, which takes the scan flags
-// usage error reported in one line: cobra prints the returned message
+// with the meaning they have for scan. Its help says what dwim runs,
-// without the usage text, and run exits 2.
+// then lists the default excludes and the filesystem types the scan
+// never records anything on.
+func newDwimCommand(stdout io.Writer) *cobra.Command {
+	var opts scanOptions
+
+	short := "Scan /, then print the duplicate-tree report"
+
+	dwimCmd := &cobra.Command{
+		Use:                   cmdDwim + " " + scanFlagsUsage,
+		DisableFlagsInUseLine: true,
+		Short:                 short,
+		Long: short + ".\n\n" + dwimHelp + "\n" +
+			defaultExcludesHelp(runtime.GOOS),
+		Args:    cobra.NoArgs,
+		PreRunE: opts.check,
+		RunE: runE(func(ctx context.Context, _ []string) error {
+			return runDwim(ctx, "/", opts, stdout)
+		}),
+	}
+	addScanFlags(dwimCmd, &opts)
+
+	return dwimCmd
+}
+
+// checkScanWorkers rejects a --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
@@ -253,6 +375,18 @@ func checkScanWorkers(cmd *cobra.Command, workers int) error {
 	return fmt.Errorf("%w, got %d", errWorkersBelowOne, workers)
 }
 
+// rejectEmptyExcludeValue rejects an empty --exclude value. That
+// is a usage error reported in one line, as for --workers below 1.
+func rejectEmptyExcludeValue(cmd *cobra.Command, excludePaths []string) error {
+	if !slices.Contains(excludePaths, "") {
+		return nil
+	}
+
+	cmd.SilenceUsage = true
+
+	return errEmptyExcludeValue
+}
+
 // 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

internal/sfdupes/cli_test.go

@@ -22,6 +22,12 @@ import (
 // error prints and a runtime failure must not.
 const usageMarker = "Usage:"
 
+// helpFlag asks for the help text.
+const helpFlag = "--help"
+
+// workersFlag is the scan and dwim flag that sets the worker count.
+const workersFlag = "--workers"
+
 // TestMain stops the tests at once, saying why, when their temporary
 // directory is not on a persistent filesystem: scan records nothing
 // there (README "Rules for the walk"), so most scan tests would fail
@@ -570,7 +576,8 @@ func TestRunNamesDefaultDatabase(t *testing.T) {
 	}{
 		cmdScan: {
 			run: func() error {
-				return runScan(t.Context(), []string{missing}, 1, false, false)
+				return runScan(t.Context(), []string{missing},
+					scanOptions{workers: 1})
 			},
 			want: scanWant,
 		},
@@ -661,7 +668,7 @@ func TestRunScanRejectsWorkersBelowOne(t *testing.T) {
 
 			var stdout, stderr bytes.Buffer
 
-			args := []string{cmdScan, "--workers", workers, t.TempDir()}
+			args := []string{cmdScan, workersFlag, workers, t.TempDir()}
 
 			code := run(args, &stdout, &stderr)
 			if code != exitUsage {
@@ -692,7 +699,7 @@ func TestRunHelp(t *testing.T) {
 
 	// README §Settings: help goes to stderr, exits 0, and leaves stdout
 	// empty.
-	cases := [][]string{{"--help"}, {"-h"}, {cmdScan, "--help"}}
+	cases := [][]string{{helpFlag}, {"-h"}, {cmdScan, helpFlag}}
 
 	for _, args := range cases {
 		var stdout, stderr bytes.Buffer
@@ -712,6 +719,112 @@ func TestRunHelp(t *testing.T) {
 				args, got)
 		}
 	}
+
+	// The scan help lists --exclude with its argument.
+	var stdout, stderr bytes.Buffer
+
+	run([]string{cmdScan, "-h"}, &stdout, &stderr)
+
+	if !strings.Contains(stderr.String(), excludeFlag+" PATH") {
+		t.Errorf("scan -h stderr = %q, want %s PATH", stderr.String(),
+			excludeFlag)
+	}
+}
+
+func TestRunScanUsageLine(t *testing.T) {
+	t.Parallel()
+
+	// README §Subcommands shows this usage line for scan, and the help
+	// and the usage error both print it.
+	const want = "\n  sfdupes scan [--workers N] [-x] [--no-default-excludes] " +
+		"[--exclude PATH]... PATH...\n"
+
+	cases := map[string][]string{
+		"help":          {cmdScan, "-h"},
+		"missing paths": {cmdScan},
+	}
+
+	for name, args := range cases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var stdout, stderr bytes.Buffer
+
+			run(args, &stdout, &stderr)
+
+			if !strings.Contains(stderr.String(), want) {
+				t.Errorf("run(%v) stderr = %q, want the usage line %q",
+					args, stderr.String(), want)
+			}
+		})
+	}
+}
+
+func TestRunHelpDescribesDatabaseAndOutput(t *testing.T) {
+	t.Parallel()
+
+	// README §Settings: the help names the database, and says what
+	// report, trees, info and dwim print.
+	database := []string{
+		"scan and dwim store", databaseEnv, defaultDatabasePath, "needs root",
+	}
+	escapes := []string{`\\`, `\t`, `\n`, `\r`}
+
+	// The subcommand whose help is printed; none for the root.
+	cases := []struct {
+		subcommand []string
+		want       []string
+	}{
+		{nil, database},
+		{[]string{cmdScan}, database},
+		{
+			[]string{cmdReport},
+			append([]string{
+				"tab-separated", "\n  first ", "\n  dupe ", "\n  size ",
+				"largest first",
+			}, escapes...),
+		},
+		{
+			[]string{cmdTrees},
+			append([]string{
+				"tab-separated", "\n  first ", "\n  dupe ", "\n  files ",
+				"\n  size ", "\n  disk_size ", "largest first",
+			}, escapes...),
+		},
+		{
+			[]string{cmdInfo},
+			[]string{
+				"\n  database ", "\n  database file size ",
+				"\n  -wal file size ", "\n  modified ",
+				"\n  schema version ", "\n  records ",
+				"\n  size of recorded files ",
+			},
+		},
+		{
+			[]string{cmdDwim},
+			[]string{
+				"sfdupes scan /", "as root", "sfdupes trees", "database",
+			},
+		},
+	}
+
+	for _, tc := range cases {
+		var stdout, stderr bytes.Buffer
+
+		args := slices.Concat(tc.subcommand, []string{helpFlag})
+
+		code := run(args, &stdout, &stderr)
+		if code != exitOK {
+			t.Fatalf("run(%v) = %d, want %d", args, code, exitOK)
+		}
+
+		for _, want := range tc.want {
+			if !strings.Contains(stderr.String(), want) {
+				t.Errorf("run(%v) help lacks %q:\n%s",
+					args, want, stderr.String())
+			}
+		}
+	}
 }
 
 func TestRunVersion(t *testing.T) {

internal/sfdupes/dwim.go

@@ -5,19 +5,20 @@ import (
 	"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
+// root" runs with the scan flags in opts, then what "sfdupes trees"
-// with a line on stderr saying how to print the report again. The dwim
+// runs, and ends with a line on stderr saying how to print the report
-// command passes "/" as root. It catches SIGINT and SIGTERM as scan
+// again. The dwim command passes "/" as root. It catches SIGINT and
-// does, but only during the scan. An error from the scan, an interrupt
+// SIGTERM as scan does, but only during the scan. An error from the
-// included, ends it before the report. During the report, a signal
+// scan, an interrupt included, ends it before the report. During the
-// ends it at once, as it ends trees.
+// report, a signal ends it at once, as it ends trees.
-func runDwim(ctx context.Context, root string, stdout io.Writer) error {
+func runDwim(
+	ctx context.Context, root string, opts scanOptions, stdout io.Writer,
+) error {
 	scanCtx, stop := interruptContext(ctx)
-	err := runScan(scanCtx, []string{root}, runtime.NumCPU(), false, false)
+	err := runScan(scanCtx, []string{root}, opts)
 
 	stop()
 

internal/sfdupes/dwim_test.go

@@ -2,7 +2,10 @@ package sfdupes //nolint:testpackage // calls the unexported runDwim
 
 import (
 	"bytes"
+	"errors"
+	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 )
@@ -28,7 +31,7 @@ func TestRunDwimPrintsLargestTreesFirst(t *testing.T) {
 
 	stderr := captureStderr(t)
 
-	err := runDwim(t.Context(), root, &stdout)
+	err := runDwim(t.Context(), root, scanOptions{workers: 1}, &stdout)
 	if err != nil {
 		t.Fatalf("runDwim: %v; stderr: %s", err, stderr())
 	}
@@ -67,7 +70,7 @@ func TestRunDwimScanErrorPrintsNoReport(t *testing.T) {
 
 	stderr := captureStderr(t)
 
-	err := runDwim(t.Context(), missing, &stdout)
+	err := runDwim(t.Context(), missing, scanOptions{workers: 1}, &stdout)
 	if err == nil {
 		t.Fatal("runDwim on a missing root: error = nil, want it fatal")
 	}
@@ -81,3 +84,127 @@ func TestRunDwimScanErrorPrintsNoReport(t *testing.T) {
 		t.Errorf("stderr = %q, want nothing from trees or dwim", got)
 	}
 }
+
+func TestRunDwimExcludeLeavesTreeOut(t *testing.T) {
+	// dwim passes its --exclude paths to the scan: an excluded copy is
+	// not recorded, so its pair is not reported.
+	t.Setenv(databaseEnv, testDBPath(t))
+
+	root := realTempDir(t)
+
+	kept := []string{
+		filepath.Dir(writeFile(t, root, "a1/f.bin", pattern(1, 300))),
+		filepath.Dir(writeFile(t, root, "a2/f.bin", pattern(1, 300))),
+	}
+	writeFile(t, root, "b1/f.bin", pattern(2, 5000))
+	excluded := filepath.Dir(writeFile(t, root, "b2/f.bin", pattern(2, 5000)))
+
+	var stdout bytes.Buffer
+
+	stderr := captureStderr(t)
+
+	opts := scanOptions{workers: 1, excludePaths: []string{excluded}}
+
+	err := runDwim(t.Context(), root, opts, &stdout)
+	if err != nil {
+		t.Fatalf("runDwim: %v; stderr: %s", err, stderr())
+	}
+
+	lines := strings.Split(strings.TrimSuffix(stdout.String(), "\n"), "\n")
+	if len(lines) != 2 {
+		t.Fatalf("stdout = %q, want a header and one group",
+			stdout.String())
+	}
+
+	want := kept[0] + "\t" + kept[1] + "\t1\t300\t"
+	if !strings.HasPrefix(lines[1], want) {
+		t.Errorf("group = %q, want it to start %q", lines[1], want)
+	}
+
+	skipped := "scan: skipped " + excluded + " (--exclude)\n"
+	if got := stderr(); !strings.Contains(got, skipped) {
+		t.Errorf("stderr = %q, want it to contain %q", got, skipped)
+	}
+}
+
+func TestRunDwimTakesScanFlags(t *testing.T) {
+	// The dwim command parses and checks the scan flags as scan does.
+	// Each case stops before the walk of / begins, and before the
+	// database is created. "dwim --exclude /" excludes its own operand.
+	cases := map[string]struct {
+		args []string
+		code int
+		want string
+	}{
+		"--exclude /": {
+			[]string{cmdDwim, excludeFlag, "/"},
+			exitFatal,
+			"sfdupes: scan /: operand excluded by --exclude /\n",
+		},
+		"--exclude empty": {
+			[]string{cmdDwim, excludeFlag, ""},
+			exitUsage,
+			"Error: --exclude must not be empty\n",
+		},
+		"--workers 0": {
+			[]string{cmdDwim, workersFlag, "0", "-x", "--no-default-excludes"},
+			exitUsage,
+			"Error: --workers must be at least 1, got 0\n",
+		},
+	}
+
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			path := testDBPath(t)
+			t.Setenv(databaseEnv, path)
+
+			stdout := captureStdout(t)
+			stderr := captureStderr(t)
+
+			code := run(tc.args, os.Stdout, os.Stderr)
+			if code != tc.code {
+				t.Errorf("run(%q) = %d, want %d", tc.args, code, tc.code)
+			}
+
+			if !strings.HasSuffix(stderr(), tc.want) || stdout() != "" {
+				t.Errorf("stdout, stderr = %q, %q, want \"\" and stderr "+
+					"ending %q", stdout(), stderr(), tc.want)
+			}
+
+			_, err := os.Lstat(path)
+			if !errors.Is(err, os.ErrNotExist) {
+				t.Errorf("lstat %s: %v, want no database", path, err)
+			}
+		})
+	}
+}
+
+func TestRunDwimHelpListsScanFlags(t *testing.T) {
+	t.Parallel()
+
+	// README "Subcommands" shows this usage line for dwim.
+	const want = "\n  sfdupes dwim [--workers N] [-x] [--no-default-excludes] " +
+		"[--exclude PATH]...\n"
+
+	var stdout, stderr bytes.Buffer
+
+	run([]string{cmdDwim, "-h"}, &stdout, &stderr)
+
+	if !strings.Contains(stderr.String(), want) {
+		t.Errorf("dwim -h stderr = %q, want the usage line %q",
+			stderr.String(), want)
+	}
+
+	if !strings.Contains(stderr.String(), excludeFlag+" PATH") {
+		t.Errorf("dwim -h stderr = %q, want %s PATH", stderr.String(),
+			excludeFlag)
+	}
+
+	// README "Settings": the help lists the default excludes and the
+	// filesystem types the walk never records anything on.
+	help := strings.TrimSpace(defaultExcludesHelp(runtime.GOOS))
+	if !strings.Contains(stderr.String(), help) {
+		t.Errorf("dwim -h stderr = %q, want it to hold %q", stderr.String(),
+			help)
+	}
+}

internal/sfdupes/exclude.go

@@ -1,8 +1,9 @@
 package sfdupes
 
-// This file holds two rules for the walk (README "Rules for the walk"):
+// This file holds three rules for the walk (README "Rules for the
+// walk"): the paths given with --exclude, which the scan never enters;
 // the default excludes, the paths a scan's walk does not enter below an
-// operand unless scan is given --no-default-excludes, and the
+// operand unless scan is given --no-default-excludes; and the
 // filesystems that are not persistent, on which the scan never records
 // or reads anything.
 
@@ -12,6 +13,7 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
+	"os"
 	"path/filepath"
 	"slices"
 	"strings"
@@ -43,17 +45,25 @@ const typesPerHelpLine = 6
 // readMountInfo reads.
 var errMountInfoLine = errors.New("unexpected line")
 
+// errExcludedOperand reports an operand at or below a path given with
+// --exclude.
+var errExcludedOperand = errors.New("operand excluded by --exclude")
+
 // walkRules holds the rules for the walk that a scan sets up as it
-// starts. excludes are the default excludes, or none with
+// starts. excludePaths are the paths given with --exclude, each with
-// --no-default-excludes. nonPersistent maps the device ID of every
+// the device ID and inode number of the file it names (see
-// mounted filesystem that is not persistent to its type; the scan
+// excludePathInodes), which the walk neither enters nor records,
-// records and reads nothing on one of those, whatever the flags.
+// whatever path leads to them. defaultExcludes are the default
-// databaseFiles are the scan's own database files, which the walk
+// excludes, or none with --no-default-excludes. nonPersistent maps the
-// passes over (see databaseFiles in db.go).
+// 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
+	excludePaths    []fileRec
-	nonPersistent map[uint64]string
+	defaultExcludes []string
-	databaseFiles []fileRec
+	nonPersistent   map[uint64]string
+	databaseFiles   []fileRec
 }
 
 // defaultExcludes returns the default excludes of the system goos
@@ -97,6 +107,88 @@ func isDefaultExclude(path string, excludes []string) bool {
 	return false
 }
 
+// excludePathInodes returns each of paths, the --exclude values, as its
+// real path (see realPaths) with the device ID and inode number of the
+// file there. The walk compares what it reaches with those, as it does
+// with the database files, so it also leaves out an --exclude path
+// spelled another way, such as in another letter case on macOS.
+func excludePathInodes(paths []string) ([]fileRec, error) {
+	resolved, err := realPaths(paths)
+	if err != nil {
+		return nil, err
+	}
+
+	files := make([]fileRec, 0, len(resolved))
+
+	for _, path := range resolved {
+		fi, err := os.Lstat(path)
+		if err != nil {
+			return nil, err
+		}
+
+		dev, ino := inodeOfInfo(fi)
+		files = append(files, fileRec{path: path, dev: dev, ino: ino})
+	}
+
+	return files, nil
+}
+
+// matchingExcludePath returns the path of the one of excludePaths with
+// the device ID and inode number of fi, an lstat result, or "" when
+// there is none.
+func matchingExcludePath(fi fs.FileInfo, excludePaths []fileRec) string {
+	dev, ino := inodeOfInfo(fi)
+	f := fileRec{dev: dev, ino: ino}
+
+	for _, exclude := range excludePaths {
+		if sameInode(exclude, f) {
+			return exclude.path
+		}
+	}
+
+	return ""
+}
+
+// checkOperandsNotExcluded returns an error when one of roots, the
+// operands, or a directory above it is one of excludePaths, the
+// --exclude paths, by device ID and inode number. The error names the
+// operand and the --exclude path. The roots are absolute, so the
+// directories above each one end at /. A path here that lstat cannot
+// read is an error too.
+func checkOperandsNotExcluded(roots []string, excludePaths []fileRec) error {
+	for _, root := range roots {
+		for path := root; ; path = filepath.Dir(path) {
+			fi, err := os.Lstat(path)
+			if err != nil {
+				return fmt.Errorf("scan %s: %w", root, err)
+			}
+
+			exclude := matchingExcludePath(fi, excludePaths)
+			if exclude != "" {
+				return fmt.Errorf("scan %s: %w %s", root, errExcludedOperand,
+					exclude)
+			}
+
+			if path == "/" {
+				break
+			}
+		}
+	}
+
+	return nil
+}
+
+// excludePathLine returns the line the scan prints for path when fi,
+// its lstat, makes it one of rules.excludePaths, and "" when it does
+// not.
+func (rules walkRules) excludePathLine(path string, fi fs.FileInfo) string {
+	if matchingExcludePath(fi, rules.excludePaths) == "" {
+		return ""
+	}
+
+	return fmt.Sprintf("scan: skipped %s (--exclude)", path)
+}
+
 // 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
@@ -162,7 +254,7 @@ func readMountInfo(mountinfo io.Reader) (map[uint64]string, error) {
 	return devices, lines.Err()
 }
 
-// defaultExcludesHelp describes, for the scan command's help, the
+// defaultExcludesHelp describes, for the scan and dwim 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 {

internal/sfdupes/exclude_test.go

@@ -14,6 +14,9 @@ import (
 	"golang.org/x/sys/unix"
 )
 
+// excludeFlag is the scan flag that names a path the walk never enters.
+const excludeFlag = "--exclude"
+
 func TestDefaultExcludes(t *testing.T) {
 	t.Parallel()
 
@@ -188,7 +191,7 @@ func TestScanDoesNotEnterDefaultExclude(t *testing.T) {
 	unseen := writeFile(t, excluded, "new", pattern(2, 10))
 
 	st, err := syncScan(t.Context(), db, []string{dir}, 1, false,
-		walkRules{excludes: []string{excluded}})
+		walkRules{defaultExcludes: []string{excluded}})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -234,7 +237,7 @@ func TestScanWalksOperandInDefaultExclude(t *testing.T) {
 			db := openTestDB(t)
 
 			st, err := syncScan(t.Context(), db, roots, 1, false,
-				walkRules{excludes: []string{excluded}})
+				walkRules{defaultExcludes: []string{excluded}})
 			if err != nil {
 				t.Fatal(err)
 			}
@@ -262,7 +265,7 @@ func TestScanNamesNoDefaultExcludeThatIsAnOperand(t *testing.T) {
 	f := writeFile(t, excluded, "f", pattern(1, 10))
 
 	st, err := syncScan(t.Context(), db, []string{dir, excluded}, 1, false,
-		walkRules{excludes: []string{excluded}})
+		walkRules{defaultExcludes: []string{excluded}})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -356,6 +359,217 @@ func TestRunScanNoDefaultExcludes(t *testing.T) {
 	assertRecorded(t, path, f, true)
 }
 
+// TestRunScanExcludeNested scans a tree through the command with an
+// --exclude path two levels below the operand. The walk records nothing
+// at or below it and says so. The record an earlier scan left there is
+// kept although its file is gone.
+func TestRunScanExcludeNested(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := realTempDir(t)
+	excluded := filepath.Join(dir, "a", "b")
+	kept := writeFile(t, dir, "a/f", pattern(1, 10))
+	gone := writeFile(t, excluded, "gone", pattern(2, 10))
+
+	scanOK(t, dir)
+
+	err := os.Remove(gone)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	unseen := writeFile(t, excluded, "c/new", pattern(3, 10))
+
+	stderr := scanOK(t, excludeFlag, excluded, dir)
+
+	line := "scan: skipped " + excluded + " (--exclude)\n"
+	if !strings.Contains(stderr, line) {
+		t.Errorf("stderr = %q, want %q", stderr, line)
+	}
+
+	assertRecorded(t, path, kept, true)
+	assertRecorded(t, path, gone, true)
+	assertRecorded(t, path, unseen, false)
+}
+
+// TestRunScanExcludeRepeated gives --exclude twice, once for a
+// directory and once for a file, the file through a symlink to it. The
+// walk records neither, and records the file beside them.
+func TestRunScanExcludeRepeated(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := realTempDir(t)
+	inDir := writeFile(t, dir, "skip/f", pattern(1, 10))
+	file := writeFile(t, dir, "skip-file", pattern(2, 10))
+	kept := writeFile(t, dir, "keep", pattern(3, 10))
+
+	link := filepath.Join(t.TempDir(), "link")
+	symlink(t, file, link)
+
+	scanOK(t, excludeFlag, filepath.Dir(inDir), excludeFlag, link, dir)
+
+	assertRecorded(t, path, inDir, false)
+	assertRecorded(t, path, file, false)
+	assertRecorded(t, path, kept, true)
+}
+
+// TestRunScanExcludeReachedByAnotherPath gives --exclude a directory
+// through a symlink and a file through "..", so the walk reaches
+// neither by the path given. The walk also reaches the file through a
+// hard link. It records none of these, prints a line naming each, and
+// records the file beside them.
+func TestRunScanExcludeReachedByAnotherPath(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := realTempDir(t)
+	inDir := writeFile(t, dir, "a/cache/f", pattern(1, 10))
+	file := writeFile(t, dir, "a/big", pattern(2, 10))
+	kept := writeFile(t, dir, "keep", pattern(3, 10))
+
+	hardLink := filepath.Join(dir, "big-link")
+
+	err := os.Link(file, hardLink)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	link := filepath.Join(t.TempDir(), "link")
+	symlink(t, filepath.Join(dir, "a"), link)
+
+	// Joined as text, since filepath.Join would drop the "..".
+	dotDot := dir + "/a/cache/../big"
+
+	stderr := scanOK(t, excludeFlag, filepath.Join(link, "cache"),
+		excludeFlag, dotDot, dir)
+
+	for _, skipped := range []string{filepath.Dir(inDir), file, hardLink} {
+		line := "scan: skipped " + skipped + " (--exclude)\n"
+		if !strings.Contains(stderr, line) {
+			t.Errorf("stderr = %q, want %q", stderr, line)
+		}
+	}
+
+	assertRecorded(t, path, inDir, false)
+	assertRecorded(t, path, file, false)
+	assertRecorded(t, path, hardLink, false)
+	assertRecorded(t, path, kept, true)
+}
+
+// TestRunScanExcludedOperand checks that an operand at or below an
+// --exclude path is a fatal error that names both, and so is an
+// --exclude path that does not exist. An operand that is a hard link to
+// an --exclude file is at it. Neither scan writes a database.
+func TestRunScanExcludedOperand(t *testing.T) {
+	dir := realTempDir(t)
+	sub := filepath.Join(dir, "sub")
+	f := writeFile(t, sub, "f", pattern(1, 10))
+
+	hardLink := filepath.Join(dir, "f-link")
+
+	err := os.Link(f, hardLink)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	cases := map[string]struct {
+		args []string
+		want string
+	}{
+		"at it": {
+			[]string{excludeFlag, sub, sub},
+			"scan " + sub + ": operand excluded by --exclude " + sub + "\n",
+		},
+		"below it": {
+			[]string{excludeFlag, dir, sub},
+			"scan " + sub + ": operand excluded by --exclude " + dir + "\n",
+		},
+		"after an operand it does not exclude": {
+			[]string{dir, excludeFlag, sub, sub},
+			"scan " + sub + ": operand excluded by --exclude " + sub + "\n",
+		},
+		"a hard link to it": {
+			[]string{excludeFlag, f, hardLink},
+			"scan " + hardLink + ": operand excluded by --exclude " + f + "\n",
+		},
+		"exclude missing": {
+			[]string{excludeFlag, filepath.Join(dir, "nope"), dir},
+			"--exclude: resolve " + filepath.Join(dir, "nope") + ": ",
+		},
+	}
+
+	for name, tc := range cases {
+		t.Run(name, func(t *testing.T) {
+			path := testDBPath(t)
+			t.Setenv(databaseEnv, path)
+
+			stdout := captureStdout(t)
+			stderr := captureStderr(t)
+
+			code := run(append([]string{cmdScan}, tc.args...), os.Stdout,
+				os.Stderr)
+			if code != exitFatal {
+				t.Errorf("run(scan %q) = %d, want %d", tc.args, code,
+					exitFatal)
+			}
+
+			assertFatalOutput(t, stderr(), stdout())
+
+			if !strings.Contains(stderr(), "sfdupes: "+tc.want) {
+				t.Errorf("stderr = %q, want %q", stderr(), tc.want)
+			}
+
+			_, err := os.Lstat(path)
+			if !errors.Is(err, os.ErrNotExist) {
+				t.Errorf("lstat %s: %v, want no database", path, err)
+			}
+		})
+	}
+}
+
+// TestRunScanRejectsEmptyExclude checks that an empty --exclude value,
+// given as its own argument, after "=" or after another --exclude, is
+// a usage error reported in one line before anything is scanned
+// (README "Settings").
+func TestRunScanRejectsEmptyExclude(t *testing.T) {
+	dir := t.TempDir()
+
+	cases := map[string][]string{
+		"separate":     {excludeFlag, "", dir},
+		"joined by =":  {excludeFlag + "=", dir},
+		"after a path": {excludeFlag, t.TempDir(), excludeFlag, "", dir},
+	}
+
+	for name, args := range cases {
+		t.Run(name, func(t *testing.T) {
+			path := testDBPath(t)
+			t.Setenv(databaseEnv, path)
+
+			var stdout, stderr bytes.Buffer
+
+			code := run(append([]string{cmdScan}, args...), &stdout,
+				&stderr)
+			if code != exitUsage {
+				t.Errorf("run(scan %q) = %d, want %d", args, code,
+					exitUsage)
+			}
+
+			want := "Error: --exclude must not be empty\n"
+			if stdout.String() != "" || stderr.String() != want {
+				t.Errorf("stdout, stderr = %q, %q, want \"\", %q",
+					stdout.String(), stderr.String(), want)
+			}
+
+			_, err := os.Lstat(path)
+			if !errors.Is(err, os.ErrNotExist) {
+				t.Errorf("lstat %s: %v, want no database", path, err)
+			}
+		})
+	}
+}
+
 // 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

internal/sfdupes/progress_test.go

@@ -642,9 +642,9 @@ func TestTerminalStalledLines(t *testing.T) {
 		{label: scanPhase("hash"), stalledOn: hashStalledOn},
 		{label: scanPhase("update"), stalledOn: "db"},
 		{label: treesPhase("read"), stalledOn: "db"},
-		{label: treesPhase("group"), stalledOn: "cpu"},
+		{label: treesPhase("group"), stalledOn: "cpu/disk"},
 		{label: treesPhase("write"), stalledOn: "out"},
-		{label: reportPhase("read"), stalledOn: "db/out"},
+		{label: reportPhase("read"), stalledOn: "db/disk/out"},
 	}
 
 	for _, params := range phases {

internal/sfdupes/report.go

@@ -4,11 +4,14 @@ import (
 	"context"
 	"crypto/sha256"
 	"database/sql"
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
 	"slices"
 	"strings"
+	"syscall"
 	"time"
 )
 
@@ -41,10 +44,10 @@ func reportPhase(name string) string {
 }
 
 // runReport implements the report subcommand: it prints the file-level
-// duplicates report as TSV on stdout. It never touches the scanned
+// duplicates report as TSV on stdout. Of the scanned filesystem it
-// filesystem; its only I/O is the database, stdout, and stderr. It
+// only checks, with pathExists, that each path in a duplicate group is
-// names the database on stderr before it opens it. Any database
+// still there. It names the database on stderr before it opens it. Any
-// problem, including a missing database, is fatal.
+// 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
@@ -77,13 +80,14 @@ func runReport(ctx context.Context, stdout io.Writer) error {
 
 	defer func() { _ = db.Close() }()
 
-	// The read phase writes the report to stdout while it reads the
+	// The read phase checks the paths of each duplicate group on disk
-	// records, so it may wait on either.
+	// and writes the report to stdout while it reads the records, so it
+	// may wait on any of the three.
 	prog = newProgress(progressParams{
 		label: reportPhase("read"), unit: "records", total: -1,
-		waitingFor: countingRecords, stalledOn: "db/out",
+		waitingFor: countingRecords, stalledOn: "db/disk/out",
 	})
-	report, err := readReport(ctx, db, dbPath, stdout, prog)
+	report, err := readReport(ctx, db, dbPath, stdout, pathExists, prog)
 
 	prog.finish()
 
@@ -104,14 +108,15 @@ func runReport(ctx context.Context, stdout io.Writer) error {
 // 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
+// read. A path for which exists returns false is left out of its group.
-// through prog's writer. It returns what it wrote, with the totals for
+// stdout may be the terminal prog is drawn on, so the lines go through
-// the summary line.
+// 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,
+	stdout io.Writer, exists func(path string) bool, prog *progress,
 ) (*reportWriter, error) {
 	out := prog.writer(stdout)
-	report := &reportWriter{out: out}
+	report := &reportWriter{out: out, exists: exists}
 
 	_, err := fmt.Fprintln(out, "first\tdupe\tsize")
 	if err != nil {
@@ -158,6 +163,10 @@ func readReport(ctx context.Context, db *sql.DB, dbPath string,
 type reportWriter struct {
 	out io.Writer
 
+	// exists reports whether a path is still on disk. A path that is
+	// gone is left out of its group.
+	exists func(path string) bool
+
 	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
@@ -194,11 +203,20 @@ func (w *reportWriter) add(r scanRec) error {
 	return nil
 }
 
-// endGroup ends the paths read with w.sig: two or more are a duplicate
+// endGroup ends the paths read with w.sig: two or more that are still
-// group, held with its paths sorted until writeGroups writes it.
+// on disk are a duplicate group, held with its paths sorted until
+// writeGroups writes it. Empty files form no group, since removing one
+// frees nothing. Only the paths of a possible group are checked, never
+// a path with no duplicate or an empty file.
 func (w *reportWriter) endGroup() {
-	if len(w.paths) < minGroupSize {
+	if len(w.paths) >= minGroupSize && w.sig.size > 0 {
-		// A path with no duplicate is dropped, and its slice reused.
+		w.paths = slices.DeleteFunc(w.paths, func(p string) bool {
+			return !w.exists(p)
+		})
+	}
+
+	if len(w.paths) < minGroupSize || w.sig.size == 0 {
+		// The paths are dropped, and their slice reused.
 		w.paths = w.paths[:0]
 
 		return
@@ -245,6 +263,16 @@ func (w *reportWriter) finish() error {
 	return w.writeGroups()
 }
 
+// pathExists reports whether path is still on disk, for report and
+// trees. It is false only when lstat finds that the path, or a
+// directory above it, is gone. Any other error counts as present, so
+// a user who may not look inside a directory still sees its copies.
+func pathExists(path string) bool {
+	_, err := os.Lstat(path)
+
+	return !errors.Is(err, fs.ErrNotExist) && !errors.Is(err, syscall.ENOTDIR)
+}
+
 // 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.

internal/sfdupes/report_test.go

@@ -72,15 +72,37 @@ type dupeGroup struct {
 	paths []string
 }
 
+// everyPathExists stands in for pathExists where a test's records name
+// made-up paths that are not on disk.
+func everyPathExists(string) bool { return true }
+
+// recsOnDisk returns a new directory and recs with each path moved
+// under it, after creating an empty file at each moved path: report and
+// trees then find every path still on disk.
+func recsOnDisk(t *testing.T, recs []scanRec) (string, []scanRec) {
+	t.Helper()
+
+	dir := realTempDir(t)
+	moved := make([]scanRec, len(recs))
+
+	for i, r := range recs {
+		r.path = writeFile(t, dir, r.path, nil)
+		moved[i] = r
+	}
+
+	return dir, moved
+}
+
 // 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.
+// each naming the group's first path. Every path counts as still on
+// disk.
 func dupeGroups(t *testing.T, db *sql.DB) []dupeGroup {
 	t.Helper()
 
 	var out bytes.Buffer
 
-	_, err := readReport(t.Context(), db, "", &out, nil)
+	_, err := readReport(t.Context(), db, "", &out, everyPathExists, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -127,7 +149,8 @@ func dupeGroupsOf(t *testing.T, recs []scanRec) []dupeGroup {
 }
 
 func TestRunReportEscapesPaths(t *testing.T) {
-	t.Setenv(databaseEnv, seedDatabase(t, awkwardPairRecs()))
+	dir, recs := recsOnDisk(t, awkwardPairRecs())
+	t.Setenv(databaseEnv, seedDatabase(t, recs))
 
 	var stdout, stderr bytes.Buffer
 
@@ -138,7 +161,7 @@ func TestRunReportEscapesPaths(t *testing.T) {
 	}
 
 	want := "first\tdupe\tsize\n" +
-		`/d/\tone\ntwo\rthree\\four/f` + "\t/d/A/f\t5\n"
+		dir + `/d/\tone\ntwo\rthree\\four/f` + "\t" + dir + "/d/A/f\t5\n"
 	if got := stdout.String(); got != want {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
@@ -172,7 +195,8 @@ func TestReportStdoutFailsWhileReading(t *testing.T) {
 	// Counts the records read, and draws nothing.
 	prog := &progress{now: time.Now}
 
-	_, err = readReport(t.Context(), db, "", failingWriter{}, prog)
+	_, err = readReport(t.Context(), db, "", failingWriter{},
+		everyPathExists, prog)
 	if !errors.Is(err, errWriteFailed) ||
 		!strings.HasPrefix(err.Error(), "write stdout: ") {
 		t.Errorf("error = %v, want write stdout: %v", err, errWriteFailed)
@@ -203,7 +227,8 @@ const smokeReport = "first\tdupe\tsize\n" +
 // 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())
+	dir, recs := recsOnDisk(t, smokeTreeRecs())
+	path := seedDatabase(t, recs)
 	t.Setenv(databaseEnv, path)
 
 	stderr := captureStderr(t)
@@ -216,8 +241,9 @@ func TestRunReportProgressNamesEachPhase(t *testing.T) {
 			code, exitOK, stderr())
 	}
 
-	if got := stdout.String(); got != smokeReport {
+	report := strings.ReplaceAll(smokeReport, "/d/", dir+"/d/")
-		t.Errorf("stdout = %q, want %q", got, smokeReport)
+	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.
@@ -266,7 +292,7 @@ func TestReadReportOnTerminal(t *testing.T) {
 		waitingFor: countingRecords,
 	}, terminalWidth, time.Hour, time.Now)
 
-	_, err = readReport(t.Context(), db, "", os.Stderr, p)
+	_, err = readReport(t.Context(), db, "", os.Stderr, everyPathExists, p)
 
 	p.finish()
 
@@ -301,6 +327,8 @@ func TestRunReportsIgnoreInsertionOrder(t *testing.T) {
 		scanRec{size: 50, head: a, tail: a, content: a, path: "/x/1"},
 	)
 
+	_, recs = recsOnDisk(t, recs)
+
 	reversed := slices.Clone(recs)
 	slices.Reverse(reversed)
 
@@ -434,6 +462,140 @@ func TestDupeGroups(t *testing.T) {
 	}
 }
 
+// TestDupeGroupsLeavesOutEmptyFiles checks that empty files form no
+// duplicate group, while 1-byte files still do.
+func TestDupeGroupsLeavesOutEmptyFiles(t *testing.T) {
+	t.Parallel()
+
+	e, x := sha256.Sum256(nil), testHash("x")
+	recs := []scanRec{
+		{size: 0, head: e, tail: e, content: e, path: "/a/.gitkeep"},
+		{size: 0, head: e, tail: e, content: e, path: "/b/.gitkeep"},
+		{size: 0, head: e, tail: e, content: e, path: "/c/__init__.py"},
+		{size: 1, head: x, tail: x, content: x, path: "/tiny1"},
+		{size: 1, head: x, tail: x, content: x, path: "/tiny2"},
+	}
+
+	groups := dupeGroupsOf(t, recs)
+	if len(groups) != 1 || groups[0].size != 1 ||
+		!slices.Equal(groups[0].paths, []string{"/tiny1", "/tiny2"}) {
+		t.Fatalf("groups = %+v, want only /tiny1 /tiny2 of size 1", groups)
+	}
+}
+
+// TestReadReportChecksOnlyPossibleDuplicates checks that report asks
+// whether a path is on disk only when its signature has two or more
+// records, and never for an empty file.
+func TestReadReportChecksOnlyPossibleDuplicates(t *testing.T) {
+	t.Parallel()
+
+	a, u, e := testHash("a"), testHash("u"), sha256.Sum256(nil)
+	recs := []scanRec{
+		{size: 9, head: a, tail: a, content: a, path: "/copy/1"},
+		{size: 9, head: a, tail: a, content: a, path: "/copy/2"},
+		{size: 9, head: a, tail: a, content: a, path: "/copy/3"},
+		{size: 9, head: u, tail: u, content: u, path: "/lonely"},
+		{size: 0, head: e, tail: e, content: e, path: "/empty1"},
+		{size: 0, head: e, tail: e, content: e, path: "/empty2"},
+	}
+
+	db := openTestDB(t)
+
+	err := applyChanges(t.Context(), db, recs, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var checked []string
+
+	exists := func(path string) bool {
+		checked = append(checked, path)
+
+		return true
+	}
+
+	_, err = readReport(t.Context(), db, "", io.Discard, exists, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	slices.Sort(checked)
+
+	want := []string{"/copy/1", "/copy/2", "/copy/3"}
+	if !slices.Equal(checked, want) {
+		t.Errorf("paths checked on disk = %q, want %q", checked, want)
+	}
+}
+
+// TestReadReportDropsGroupLeftWithOnePath checks that a group of two
+// paths, one of them gone, is no duplicate group. If kept, it would
+// write no row, but the summary line would count it.
+func TestReadReportDropsGroupLeftWithOnePath(t *testing.T) {
+	t.Parallel()
+
+	a := testHash("a")
+	recs := []scanRec{
+		{size: 9, head: a, tail: a, content: a, path: "/a/kept"},
+		{size: 9, head: a, tail: a, content: a, path: "/a/gone"},
+	}
+
+	db := openTestDB(t)
+
+	err := applyChanges(t.Context(), db, recs, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	exists := func(path string) bool { return path != "/a/gone" }
+
+	report, err := readReport(t.Context(), db, "", io.Discard, exists, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if report.dupeGroups != 0 {
+		t.Errorf("duplicate groups = %d, want 0", report.dupeGroups)
+	}
+}
+
+// TestReadReportKeepsGroupLeftWithTwoPaths checks that a group of three
+// paths, one of them gone, is a duplicate group of the other two.
+func TestReadReportKeepsGroupLeftWithTwoPaths(t *testing.T) {
+	t.Parallel()
+
+	a := testHash("a")
+	recs := []scanRec{
+		{size: 9, head: a, tail: a, content: a, path: "/b/kept1"},
+		{size: 9, head: a, tail: a, content: a, path: "/b/gone"},
+		{size: 9, head: a, tail: a, content: a, path: "/b/kept2"},
+	}
+
+	db := openTestDB(t)
+
+	err := applyChanges(t.Context(), db, recs, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	exists := func(path string) bool { return path != "/b/gone" }
+
+	var out bytes.Buffer
+
+	report, err := readReport(t.Context(), db, "", &out, exists, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if report.dupeGroups != 1 {
+		t.Errorf("duplicate groups = %d, want 1", report.dupeGroups)
+	}
+
+	want := "first\tdupe\tsize\n/b/kept1\t/b/kept2\t9\n"
+	if got := out.String(); got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+}
+
 func TestDupeGroupsContentSeparates(t *testing.T) {
 	t.Parallel()
 

internal/sfdupes/scan.go

@@ -98,44 +98,47 @@ func scanPhase(name string) string {
 // runs, and the lock is released after it. When ctx is cancelled, as by
 // the SIGINT or SIGTERM that interruptContext catches, the scan keeps
 // what it has hashed (see syncScan), prints how many files its walk
-// reached, and returns errInterrupted. workers must be at least 1; the
+// reached, and returns errInterrupted. opts.workers must be at least 1;
-// scan command rejects anything less. Before the lock is taken, the
+// the scan and dwim commands reject anything less. Before the lock is
-// scan lists the filesystems that are not persistent, on which the walk
+// taken, the scan lists the filesystems that are not persistent, on
-// records nothing; unless noDefaultExcludes is set, the walk does not
+// which the walk records nothing; unless opts.noDefaultExcludes is set,
-// enter the default excludes either. Once the database is open, the
+// the walk does not enter the default excludes either. The walk neither
-// scan notes its files, which the walk passes over.
+// enters nor records the paths in opts.excludePaths, the --exclude
-func runScan(ctx context.Context, roots []string, workers int,
+// values; an operand at or below one is a fatal error. Once the
-	oneFS, noDefaultExcludes bool,
+// database is open, the scan notes its files, which the walk passes
-) error {
+// over.
+func runScan(ctx context.Context, roots []string, opts scanOptions) error {
 	dbPath, source, err := databasePath()
 	if err != nil {
 		return err
 	}
 
-	// A database file missing now is created by lockScanDatabase below.
+	printDatabasePath(dbPath, source)
-	what := "database"
 
-	_, err = os.Stat(dbPath)
+	roots, err = realPaths(roots)
-	if errors.Is(err, fs.ErrNotExist) {
-		what = "new database"
-	}
-
-	fmt.Fprintf(os.Stderr, "scan: %s %s (%s)\n", what, escapePath(dbPath),
-		source)
-
-	roots, err = resolveRoots(roots)
 	if err != nil {
 		return err
 	}
 
-	nonPersistent, err := nonPersistentFilesystems()
+	var rules walkRules
+
+	rules.excludePaths, err = excludePathInodes(opts.excludePaths)
+	if err != nil {
+		return fmt.Errorf("--exclude: %w", err)
+	}
+
+	err = checkOperandsNotExcluded(roots, rules.excludePaths)
+	if err != nil {
+		return err
+	}
+
+	rules.nonPersistent, err = nonPersistentFilesystems()
 	if err != nil {
 		return fmt.Errorf("list the mounted filesystems: %w", err)
 	}
 
-	rules := walkRules{nonPersistent: nonPersistent}
+	if !opts.noDefaultExcludes {
-	if !noDefaultExcludes {
+		rules.defaultExcludes = defaultExcludes(runtime.GOOS)
-		rules.excludes = defaultExcludes(runtime.GOOS)
 	}
 
 	lock, err := lockScanDatabase(dbPath)
@@ -163,7 +166,7 @@ func runScan(ctx context.Context, roots []string, workers int,
 		return err
 	}
 
-	st, err := syncScan(ctx, db, roots, workers, oneFS, rules)
+	st, err := syncScan(ctx, db, roots, opts.workers, opts.oneFS, rules)
 	if errors.Is(err, context.Canceled) {
 		return interrupted(st.walked)
 	}
@@ -181,6 +184,21 @@ func runScan(ctx context.Context, roots []string, workers int,
 	return nil
 }
 
+// printDatabasePath prints on stderr the line that names the database
+// at dbPath, with source, saying whether it is new. A database file
+// missing now is new: lockScanDatabase creates it.
+func printDatabasePath(dbPath, source string) {
+	what := "database"
+
+	_, err := os.Stat(dbPath)
+	if errors.Is(err, fs.ErrNotExist) {
+		what = "new database"
+	}
+
+	fmt.Fprintf(os.Stderr, "scan: %s %s (%s)\n", what, escapePath(dbPath),
+		source)
+}
+
 // interruptContext returns a copy of ctx that the first SIGINT or
 // SIGTERM cancels; the scan command runs the scan under it. stop
 // releases the signals.
@@ -209,24 +227,25 @@ func interrupted(walked int) error {
 	return errInterrupted
 }
 
-// resolveRoots converts each PATH operand to its real path: absolute,
+// realPaths returns the real path of each of paths, the PATH operands
-// with every symlink in it followed. Database records are keyed by
+// or the --exclude values: absolute, with every symlink in it followed.
-// that path, so scan results depend neither on the working directory
+// Database records are keyed by that path, so scan results depend
-// nor on the symlinks an operand was given through. An operand that
+// neither on the working directory nor on the symlinks an operand was
-// cannot be resolved, because it or a symlink's target does not exist
+// given through. A path that cannot be resolved, because it or a
-// or cannot be read, is a fatal error before any scanning.
+// symlink's target does not exist or cannot be read, is a fatal error
-func resolveRoots(roots []string) ([]string, error) {
+// before any scanning.
-	resolved := make([]string, 0, len(roots))
+func realPaths(paths []string) ([]string, error) {
+	resolved := make([]string, 0, len(paths))
 
-	for _, root := range roots {
+	for _, path := range paths {
-		a, err := absolutePath(root)
+		a, err := absolutePath(path)
 		if err != nil {
-			return nil, fmt.Errorf("resolve %s: %w", root, err)
+			return nil, fmt.Errorf("resolve %s: %w", path, err)
 		}
 
 		r, err := filepath.EvalSymlinks(a)
 		if err != nil {
-			return nil, fmt.Errorf("resolve %s: %w", root, err)
+			return nil, fmt.Errorf("resolve %s: %w", path, err)
 		}
 
 		resolved = append(resolved, r)
@@ -295,7 +314,7 @@ func walkReaches(above, r string, oneFS bool, rules walkRules,
 	}
 
 	for ; dir != above; dir = filepath.Dir(dir) {
-		if isDefaultExclude(dir, rules.excludes) {
+		if isDefaultExclude(dir, rules.defaultExcludes) {
 			return false
 		}
 
@@ -418,7 +437,7 @@ func (s *scanState) runPhases(ctx context.Context, roots []string,
 
 // walkableRoots returns the operands the walk can start from: regular
 // files, and directories not named .zfs, none of them inside a
-// directory named .zfs. The operands are real paths from resolveRoots,
+// directory named .zfs. The operands are real paths from realPaths,
 // so these checks apply to what a symlink operand points at. Every
 // other operand is warned about, counted as skipped, and dropped. A
 // dropped operand is no longer a root, so the records stored beneath it
@@ -493,10 +512,11 @@ func (s *scanState) loadIndex(ctx context.Context, roots []string) error {
 // as verified. When its disk_size differs from the record's, it is
 // queued for the update phase, which writes the new disk_size. A record
 // at or below a path the walk left out, because -x stopped at it, it is
-// a default exclude, or it is not on a persistent filesystem, counts as
+// an --exclude path or a default exclude, or it is not on a persistent
-// outside the roots: it is not deleted. That does not hold below a root
+// filesystem, counts as outside the roots: it is not deleted. That does
-// at or inside that path, since that root's own walk verifies the
+// not hold below a root at or inside that path, since that root's own
-// records below it; nor is a line printed for such a root.
+// walk verifies the records below it; nor is a line printed for such a
+// root.
 func (s *scanState) walkPhase(events <-chan walkEvent, roots []string) {
 	// The records the last scan left under the roots estimate how many
 	// files the walk will find. A first scan has none, and no estimate.
@@ -545,7 +565,7 @@ func (s *scanState) walkPhase(events <-chan walkEvent, roots []string) {
 		prog.increment()
 
 		old, ok := s.existing[ev.rec.path]
-		if !ok || old.size != ev.rec.size || mtimeAfter(ev.rec.mtime, old.mtime) {
+		if !ok || old.size != ev.rec.size || !ev.rec.mtime.Equal(old.mtime) {
 			s.toHash = append(s.toHash, ev.rec)
 
 			continue
@@ -780,16 +800,6 @@ func (s *scanState) updatePhase(ctx context.Context) error {
 	return applyChanges(ctx, s.db, nil, deletes, prog)
 }
 
-// mtimeAfter reports whether mtime a is later than mtime b.
-// Not a.After(b): time.Time wraps an mtime past year 292 billion; Unix() undoes it.
-func mtimeAfter(a, b time.Time) bool {
-	if a.Unix() != b.Unix() {
-		return a.Unix() > b.Unix()
-	}
-
-	return a.Nanosecond() > b.Nanosecond()
-}
-
 // underAnyRoot reports whether path is any of the roots or lies under
 // one of them.
 func underAnyRoot(path string, roots []string) bool {
@@ -844,9 +854,9 @@ type dirJob struct {
 // file's statted record, a warning when fail is set, or a path the walk
 // left out: when otherFSDir is set, a directory -x did not enter
 // because it is on another filesystem than its operand, and when
-// leftOut is set, a default exclude or a directory or file on a
+// leftOut is set, an --exclude path, a default exclude or a directory or
-// filesystem that is not persistent, with warn holding the line that
+// file on a filesystem that is not persistent, with warn holding the
-// says so.
+// line that says so.
 type walkEvent struct {
 	rec        fileRec
 	warn       string
@@ -897,7 +907,7 @@ func sendEvent(ctx context.Context, events chan<- walkEvent,
 // operandWarning returns the one-line warning for an operand the walk
 // does not start from, naming the path and what it is, or "" for one it
 // does: a regular file, or a directory not named .zfs, that is not
-// inside a directory named .zfs. resolveRoots has already followed the
+// inside a directory named .zfs. realPaths has already followed the
 // operand's symlinks, so a symlink here is an operand replaced by one
 // after it was resolved, and is not followed.
 func operandWarning(root string, fi fs.FileInfo) string {
@@ -1128,8 +1138,9 @@ func walkOneDir(ctx context.Context, job dirJob, oneFS bool,
 // no longer exists, and one that has stopped being a regular file is
 // skipped. A file on a filesystem in rules that is not persistent, as
 // through a bind mount of one file, is not recorded: it gets an event
-// naming it instead. One of the scan's own database files in rules gets
+// naming it instead, and so does a file given with --exclude, reached
-// no event at all.
+// by any path, a hard link to it included. One of the scan's own
+// database files in rules gets no event at all.
 func emitFile(ctx context.Context, p string, e fs.DirEntry,
 	rules walkRules, events chan<- walkEvent,
 ) {
@@ -1153,6 +1164,10 @@ func emitFile(ctx context.Context, p string, e fs.DirEntry,
 	}
 
 	line := rules.nonPersistentLine(p, info)
+	if line == "" {
+		line = rules.excludePathLine(p, info)
+	}
+
 	if line != "" {
 		sendEvent(ctx, events, walkEvent{leftOut: p, warn: line})
 
@@ -1177,11 +1192,11 @@ func emitFile(ctx context.Context, p string, e fs.DirEntry,
 // subdirJob applies the descent rules to directory p: never enter
 // .zfs (ZFS snapshot pseudo-dirs would list every file once per
 // snapshot), never enter a directory on a filesystem in rules that is
-// not persistent, nor a default exclude in rules, and with -x never
+// not persistent, nor an --exclude path or a default exclude in rules,
-// enter a directory on a different filesystem than its operand. For the
+// and with -x never enter a directory on a different filesystem than
-// last three it sends an event that names the directory, so the scan
+// its operand. For all but .zfs it sends an event that names the
-// keeps the records below it, except those below an operand at or
+// directory, so the scan keeps the records below it, except those below
-// inside it.
+// an operand at or inside it.
 func subdirJob(ctx context.Context, p string, e fs.DirEntry,
 	parent dirJob, oneFS bool, rules walkRules,
 	events chan<- walkEvent,
@@ -1206,13 +1221,17 @@ func subdirJob(ctx context.Context, p string, e fs.DirEntry,
 	}
 
 	line := rules.nonPersistentLine(p, info)
+	if line == "" {
+		line = rules.excludePathLine(p, info)
+	}
+
 	if line != "" {
 		sendEvent(ctx, events, walkEvent{leftOut: p, warn: line})
 
 		return dirJob{}, false
 	}
 
-	if isDefaultExclude(p, rules.excludes) {
+	if isDefaultExclude(p, rules.defaultExcludes) {
 		sendEvent(ctx, events, walkEvent{
 			leftOut: p,
 			warn:    fmt.Sprintf("scan: skipped %s (default exclude)", p),

internal/sfdupes/scan_test.go

@@ -1185,11 +1185,12 @@ func assertSmokeDupeGroups(t *testing.T, dir string, db *sql.DB) {
 	t.Helper()
 
 	groups := dupeGroups(t, db)
-	if len(groups) != 5 {
+	if len(groups) != 4 {
-		t.Fatalf("len(groups) = %d, want 5", len(groups))
+		t.Fatalf("len(groups) = %d, want 4", len(groups))
 	}
 
-	wantSizes := []int64{3000, 2000, 100, 1, 0}
+	// The empty files empty1 and empty2 form no group.
+	wantSizes := []int64{3000, 2000, 100, 1}
 	for i, g := range groups {
 		if g.size != wantSizes[i] {
 			t.Errorf("groups[%d].size = %d, want %d",
@@ -1214,7 +1215,7 @@ func assertSmokeTreeGroups(t *testing.T, dir string, db *sql.DB) {
 
 	super, dirs := dbTree(t, db)
 
-	tg := collectTreeGroups(dirs, super, nil)
+	tg := collectTreeGroups(dirs, super, everyPathExists, nil)
 	if len(tg) != 1 {
 		t.Fatalf("len(tree groups) = %d, want 1", len(tg))
 	}
@@ -1383,6 +1384,47 @@ func TestSyncScanMtimeBump(t *testing.T) {
 	}
 }
 
+// TestSyncScanMtimeMovedBack replaces a file with other content of the
+// same size and an older mtime, as cp -p or a restore from backup does.
+// The next scan must hash the file again.
+func TestSyncScanMtimeMovedBack(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	db := openTestDB(t)
+	a := writeFile(t, dir, "a.bin", pattern(1, 500))
+
+	recorded := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)
+
+	err := os.Chtimes(a, recorded, recorded)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	syncTree(t, db, dir)
+
+	replaced := pattern(3, 500)
+	writeFile(t, dir, "a.bin", replaced)
+
+	older := recorded.Add(-time.Hour)
+
+	err = os.Chtimes(a, older, older)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	st := syncTree(t, db, dir)
+	if st != (scanStats{walked: 1, updated: 1}) {
+		t.Fatalf("rescan stats = %+v, want 1 updated", st)
+	}
+
+	assertWholeFileHashed(t, db, a, replaced)
+
+	if r := recordByPath(t, dbRecords(t, db), a); !r.mtime.Equal(older) {
+		t.Fatalf("mtime = %v, want %v", r.mtime, older)
+	}
+}
+
 // assertWholeFileHashed fails unless the record for path holds the
 // whole-file hash of data as its head, tail, and content.
 func assertWholeFileHashed(t *testing.T, db *sql.DB, path string,
@@ -2154,7 +2196,7 @@ func TestScanHashWriteFailureUnwindsPool(t *testing.T) {
 	var stderr bytes.Buffer
 
 	code := run([]string{
-		cmdScan, "--workers", strconv.Itoa(hashLeakWorkers), dir,
+		cmdScan, workersFlag, strconv.Itoa(hashLeakWorkers), dir,
 	}, io.Discard, &stderr)
 	if code != exitFatal {
 		t.Fatalf("run(scan) = %d, want %d; stderr: %s",
@@ -2247,7 +2289,7 @@ func TestPruneRoots(t *testing.T) {
 
 	// The walk of /p does not enter /p/q when it is a default exclude, so
 	// /p/q is kept, without -x too; /p/q/r lies under it and is dropped.
-	got = pruneRoots(nested, false, walkRules{excludes: []string{pqRoot}},
+	got = pruneRoots(nested, false, walkRules{defaultExcludes: []string{pqRoot}},
 		device)
 	if !slices.Equal(got, want) {
 		t.Fatalf("pruneRoots excluding %s = %q, want %q", pqRoot, got, want)
@@ -2265,23 +2307,86 @@ func TestPruneRoots(t *testing.T) {
 	}
 }
 
-func TestReportsNeverTouchFilesystem(t *testing.T) {
+// TestRunReportsLeaveOutRemovedCopies scans the smoke tree, then
-	t.Parallel()
+// removes copies the reports name. report leaves out each removed file,
+// and a group left with one path. trees checks only the root of each
+// duplicate tree: with a file under t2 removed it still names t2, and
+// with t2 removed it names nothing.
+func TestRunReportsLeaveOutRemovedCopies(t *testing.T) {
+	t.Setenv(databaseEnv, testDBPath(t))
 
 	dir := buildSmokeTree(t)
-	db := openTestDB(t)
+	p := func(name string) string { return filepath.Join(dir, name) }
 
-	syncTree(t, db, dir)
+	scanOK(t, dir)
 
-	// Remove the scanned tree entirely; the analysis must be
+	for _, name := range []string{"b/copy2.bin", "tiny2", "t2/sub/f2"} {
-	// unaffected because it reads the database alone.
+		err := os.Remove(p(name))
-	err := os.RemoveAll(dir)
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	want := "first\tdupe\tsize\n" +
+		p("t1/f1") + "\t" + p("t2/f1") + "\t3000\n" +
+		p("t1/f1") + "\t" + p("t3/f1") + "\t3000\n" +
+		p("a/one.bin") + "\t" + p("b/copy.bin") + "\t2000\n" +
+		p("t1/sub/f2") + "\t" + p("t3/sub/f2renamed") + "\t100\n"
+	if got := runStdout(t, cmdReport); got != want {
+		t.Errorf("report stdout = %q, want %q", got, want)
+	}
+
+	// disk_size, the last column, depends on the filesystem.
+	header := "first\tdupe\tfiles\tsize\tdisk_size\n"
+
+	want = header + p("t1") + "\t" + p("t2") + "\t2\t3100\t"
+	if got := runStdout(t, cmdTrees); !strings.HasPrefix(got, want) ||
+		strings.Count(got, "\n") != 2 {
+		t.Errorf("trees stdout = %q, want one row starting %q", got, want)
+	}
+
+	err := os.RemoveAll(p("t2"))
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	assertSmokeDupeGroups(t, dir, db)
+	if got := runStdout(t, cmdTrees); got != header {
-	assertSmokeTreeGroups(t, dir, db)
+		t.Errorf("trees stdout after removing t2 = %q, want %q", got, header)
+	}
+}
+
+func TestPathExists(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	file := writeFile(t, dir, "file", nil)
+	locked := writeFile(t, dir, "locked/file", nil)
+
+	// Without search permission on its directory, a file cannot be
+	// looked at by anyone but root.
+	err := os.Chmod(filepath.Dir(locked), 0)
+	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(filepath.Dir(locked), 0o700)
+	})
+
+	cases := map[string]bool{
+		dir:                                 true,
+		file:                                true,
+		locked:                              true,
+		filepath.Join(dir, "gone"):          false,
+		filepath.Join(file, "under-a-file"): false,
+	}
+	for path, want := range cases {
+		if got := pathExists(path); got != want {
+			t.Errorf("pathExists(%q) = %v, want %v", path, got, want)
+		}
+	}
 }
 
 func TestUnderRoot(t *testing.T) {
@@ -2367,8 +2472,8 @@ func TestRunScanPassesOverDatabase(t *testing.T) {
 			report := runStdout(t, cmdReport)
 			if strings.Contains(report, "db.sqlite") ||
 				strings.Contains(report, hardLink) ||
-				!strings.Contains(report, filepath.Join(tree, "empty2")) {
+				!strings.Contains(report, filepath.Join(tree, "b")) {
-				t.Errorf("report = %q, want the empty files and none of "+
+				t.Errorf("report = %q, want a and b and none of "+
 					"the database's files", report)
 			}
 		})

internal/sfdupes/trees.go

@@ -38,10 +38,11 @@ func treesPhase(name string) string {
 // 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
+// prints maximal duplicate-tree groups as TSV on stdout. Of the scanned
-// touches the scanned filesystem; its only I/O is the database, stdout,
+// filesystem it only checks, with pathExists, that the root of each
-// and stderr. It names the database on stderr before it opens it. Any
+// duplicate tree is still there, never the files below it. It names the
-// database problem, including a missing database, is fatal.
+// 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
@@ -86,13 +87,13 @@ func runTrees(ctx context.Context, stdout io.Writer) error {
 		return fmt.Errorf("database %s: %w", dbPath, err)
 	}
 
-	// Grouping works in memory, so it waits on nothing but the
+	// Grouping works in memory, then checks the root of each duplicate
-	// processor.
+	// tree on disk, so it waits on the processor or the disk.
 	prog = newProgress(progressParams{
 		label: treesPhase("group"), unit: "directories",
-		total: int64(len(allDirs)), stalledOn: "cpu",
+		total: int64(len(allDirs)), stalledOn: "cpu/disk",
 	})
-	dupes := collectTreeGroups(allDirs, super, prog)
+	dupes := collectTreeGroups(allDirs, super, pathExists, prog)
 
 	prog.finish()
 
@@ -100,7 +101,7 @@ func runTrees(ctx context.Context, stdout io.Writer) error {
 		label: treesPhase("write"), unit: "groups", total: int64(len(dupes)),
 		stalledOn: "out",
 	})
-	dupeTrees, reclaimable, err := writeTreeGroups(stdout, dupes, prog)
+	dupeTrees, err := writeTreeGroups(stdout, dupes, prog)
 
 	prog.finish()
 
@@ -111,7 +112,7 @@ func runTrees(ctx context.Context, stdout io.Writer) error {
 	fmt.Fprintf(os.Stderr,
 		"trees: %d records read, %d duplicate tree groups, %d dupe trees, "+
 			"%s reclaimable\n",
-		records, len(dupes), dupeTrees, humanBytes(reclaimable))
+		records, len(dupes), dupeTrees, humanBytes(reclaimableBytes(dupes)))
 
 	return nil
 }
@@ -145,22 +146,19 @@ func readTree(ctx context.Context, db *sql.DB,
 // 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)
+// 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) {
+) (int, 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)
+		return 0, fmt.Errorf("write stdout: %w", err)
 	}
 
 	dupeTrees := 0
 
-	var reclaimable int64
-
 	for _, g := range dupes {
 		first := g[0]
 		for _, n := range g[1:] {
@@ -168,11 +166,10 @@ func writeTreeGroups(stdout io.Writer, dupes [][]*treeNode,
 				escapePath(first.path), escapePath(n.path),
 				first.fileCount, first.totalSize, n.diskSize)
 			if err != nil {
-				return 0, 0, fmt.Errorf("write stdout: %w", err)
+				return 0, fmt.Errorf("write stdout: %w", err)
 			}
 
 			dupeTrees++
-			reclaimable += first.totalSize
 		}
 
 		prog.increment()
@@ -180,10 +177,44 @@ func writeTreeGroups(stdout io.Writer, dupes [][]*treeNode,
 
 	err = out.Flush()
 	if err != nil {
-		return 0, 0, fmt.Errorf("write stdout: %w", err)
+		return 0, fmt.Errorf("write stdout: %w", err)
 	}
 
-	return dupeTrees, reclaimable, nil
+	return dupeTrees, nil
+}
+
+// reclaimableBytes returns the sum of the size column over the rows
+// that writeTreeGroups writes for dupes, leaving out a row whose dupe
+// lies inside another row's dupe.
+func reclaimableBytes(dupes [][]*treeNode) int64 {
+	isDupe := make(map[*treeNode]bool)
+
+	for _, g := range dupes {
+		for _, n := range g[1:] {
+			isDupe[n] = true
+		}
+	}
+
+	var total int64
+
+	for n := range isDupe {
+		if !insideDupe(n, isDupe) {
+			total += n.totalSize
+		}
+	}
+
+	return total
+}
+
+// insideDupe reports whether a directory above n is in isDupe.
+func insideDupe(n *treeNode, isDupe map[*treeNode]bool) bool {
+	for p := n.parent; p != nil; p = p.parent {
+		if isDupe[p] {
+			return true
+		}
+	}
+
+	return false
 }
 
 // treeBuilder reconstructs the directory hierarchy from records added
@@ -300,10 +331,14 @@ func fileEntry(name string, r scanRec) string {
 
 // 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
+// more members for which exists returns true, each group's members
-// tree size descending then by first path ascending.
+// sorted by path, groups ordered by tree size descending then by first
+// path ascending. A group whose trees hold 0 bytes is left out, since
+// removing one frees nothing. The groups it implies hold 0 bytes too,
+// so leaving it out hides nothing. exists is called only on the members
+// of maximal groups.
 func collectTreeGroups(allDirs []*treeNode, super *treeNode,
-	prog *progress,
+	exists func(path string) bool, prog *progress,
 ) [][]*treeNode {
 	groups := make(map[[sha256.Size]byte][]*treeNode)
 	for _, d := range allDirs {
@@ -315,7 +350,19 @@ func collectTreeGroups(allDirs []*treeNode, super *treeNode,
 	var dupes [][]*treeNode
 
 	for _, g := range groups {
-		if len(g) < minGroupSize || suppressed(g, super) {
+		// The members share a digest, so they share a total size.
+		if len(g) < minGroupSize || g[0].totalSize == 0 ||
+			suppressed(g, super) {
+			continue
+		}
+
+		// A member that is gone leaves the group. A suppressed group is
+		// still implied: its members still on disk have parents still
+		// on disk, and those parents' group is checked the same way.
+		g = slices.DeleteFunc(g, func(n *treeNode) bool {
+			return !exists(n.path)
+		})
+		if len(g) < minGroupSize {
 			continue
 		}
 

internal/sfdupes/trees_test.go

@@ -2,9 +2,11 @@ package sfdupes //nolint:testpackage // checks the unexported treeNode results
 
 import (
 	"bytes"
+	"crypto/sha256"
 	"database/sql"
 	"os"
 	"slices"
+	"strconv"
 	"strings"
 	"testing"
 	"time"
@@ -178,7 +180,7 @@ func TestTreeNamesSortingBeforeSlash(t *testing.T) {
 		t.Fatalf("directory paths = %q, want %q", got, want)
 	}
 
-	groups := collectTreeGroups(dirs, super, nil)
+	groups := collectTreeGroups(dirs, super, everyPathExists, nil)
 
 	gotGroups := groupPaths(groups)
 	wantGroups := [][]string{{"/a", "/c"}}
@@ -194,7 +196,8 @@ func TestTreeNamesSortingBeforeSlash(t *testing.T) {
 }
 
 func TestRunTreesEscapesPaths(t *testing.T) {
-	t.Setenv(databaseEnv, seedDatabase(t, awkwardPairRecs()))
+	dir, recs := recsOnDisk(t, awkwardPairRecs())
+	t.Setenv(databaseEnv, seedDatabase(t, recs))
 
 	var stdout, stderr bytes.Buffer
 
@@ -205,7 +208,7 @@ func TestRunTreesEscapesPaths(t *testing.T) {
 	}
 
 	want := "first\tdupe\tfiles\tsize\tdisk_size\n" +
-		`/d/\tone\ntwo\rthree\\four` + "\t/d/A\t1\t5\t4096\n"
+		dir + `/d/\tone\ntwo\rthree\\four` + "\t" + dir + "/d/A\t1\t5\t4096\n"
 	if got := stdout.String(); got != want {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
@@ -223,9 +226,11 @@ func TestRunTreesDiskSize(t *testing.T) {
 		{size: 20, diskSize: 1024, head: g, tail: g, content: g, path: "/b/sub/g"},
 	}
 
+	dir, recs := recsOnDisk(t, recs)
 	t.Setenv(databaseEnv, seedDatabase(t, recs))
 
-	want := "first\tdupe\tfiles\tsize\tdisk_size\n/a\t/b\t2\t30\t1536\n"
+	want := "first\tdupe\tfiles\tsize\tdisk_size\n" +
+		dir + "/a\t" + dir + "/b\t2\t30\t1536\n"
 	if got := runStdout(t, cmdTrees); got != want {
 		t.Errorf("stdout = %q, want %q", got, want)
 	}
@@ -236,10 +241,11 @@ func TestRunTreesDiskSize(t *testing.T) {
 // 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
+// the 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())
+	dir, recs := recsOnDisk(t, smokeTreeRecs())
+	path := seedDatabase(t, recs)
 	t.Setenv(databaseEnv, path)
 
 	stderr := captureStderr(t)
@@ -253,11 +259,15 @@ func TestRunTreesProgressNamesEachPhase(t *testing.T) {
 	}
 
 	report := "first\tdupe\tfiles\tsize\tdisk_size\n" +
-		"/d/t1\t/d/t2\t2\t3100\t8192\n"
+		dir + "/d/t1\t" + dir + "/d/t2\t2\t3100\t8192\n"
 	if got := stdout.String(); got != report {
 		t.Errorf("stdout = %q, want %q", got, report)
 	}
 
+	// The smoke-test records name 8 directories, / included. Moved under
+	// dir, they name one more for each slash in dir.
+	dirs := strconv.Itoa(8 + strings.Count(dir, "/"))
+
 	// How each line starts; the rate at the end of a phase varies.
 	want := []string{
 		"trees: database " + path + " (from " + databaseEnv + ")",
@@ -265,8 +275,9 @@ func TestRunTreesProgressNamesEachPhase(t *testing.T) {
 		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: [0/" + dirs + "] 0%, 0 directories/s, elapsed 0s, " +
-		"[3/4] group: [8/8] 100%, ",
+			"remain unknown",
+		"[3/4] group: [" + dirs + "/" + dirs + "] 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, ",
@@ -295,14 +306,14 @@ func TestRunTreesProgressNamesEachPhase(t *testing.T) {
 func TestWriteTreeGroupsOnTerminal(t *testing.T) {
 	stderr := captureStderr(t)
 	super, dirs := treeOf(t, smokeTreeRecs())
-	dupes := collectTreeGroups(dirs, super, nil)
+	dupes := collectTreeGroups(dirs, super, everyPathExists, 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)
+	_, err := writeTreeGroups(os.Stderr, dupes, p)
 
 	p.finish()
 
@@ -376,7 +387,7 @@ func TestCollectTreeGroupsMaximal(t *testing.T) {
 
 	super, dirs := treeOf(t, smokeTreeRecs())
 
-	groups := collectTreeGroups(dirs, super, nil)
+	groups := collectTreeGroups(dirs, super, everyPathExists, nil)
 
 	want := [][]string{{"/d/t1", "/d/t2"}}
 	if got := groupPaths(groups); !slices.EqualFunc(got, want,
@@ -400,14 +411,16 @@ func TestCollectTreeGroupsDeterministic(t *testing.T) {
 
 	super, dirs := treeOf(t, recs)
 
-	forward := groupPaths(collectTreeGroups(dirs, super, nil))
+	forward := groupPaths(collectTreeGroups(dirs, super, everyPathExists,
+		nil))
 
 	reversed := slices.Clone(recs)
 	slices.Reverse(reversed)
 
 	superR, dirsR := treeOf(t, reversed)
 
-	backward := groupPaths(collectTreeGroups(dirsR, superR, nil))
+	backward := groupPaths(collectTreeGroups(dirsR, superR, everyPathExists,
+		nil))
 	if !slices.EqualFunc(forward, backward, slices.Equal) {
 		t.Fatalf("output depends on record order: %v vs %v",
 			forward, backward)
@@ -427,7 +440,36 @@ func TestCollectTreeGroupsSiblings(t *testing.T) {
 
 	super, dirs := treeOf(t, recs)
 
-	got := groupPaths(collectTreeGroups(dirs, super, nil))
+	got := groupPaths(collectTreeGroups(dirs, super, everyPathExists, nil))
+
+	want := [][]string{{"/p/x1", "/p/x2"}}
+	if !slices.EqualFunc(got, want, slices.Equal) {
+		t.Fatalf("groups = %v, want %v", got, want)
+	}
+}
+
+// TestCollectTreeGroupsLeavesOutEmptyTrees checks that directories
+// holding only empty files form no group, and that an empty file still
+// counts toward the digest of a tree that holds other files.
+func TestCollectTreeGroupsLeavesOutEmptyTrees(t *testing.T) {
+	t.Parallel()
+
+	h, tl, c, e := testHash("h"), testHash("t"), testHash("c"),
+		sha256.Sum256(nil)
+	recs := []scanRec{
+		{size: 0, head: e, tail: e, content: e, path: "/e/a/.gitkeep"},
+		{size: 0, head: e, tail: e, content: e, path: "/e/b/.gitkeep"},
+		{size: 10, head: h, tail: tl, content: c, path: "/p/x1/f"},
+		{size: 0, head: e, tail: e, content: e, path: "/p/x1/.gitkeep"},
+		{size: 10, head: h, tail: tl, content: c, path: "/p/x2/f"},
+		{size: 0, head: e, tail: e, content: e, path: "/p/x2/.gitkeep"},
+		// Without the empty file, /p/x3 is no copy of /p/x1.
+		{size: 10, head: h, tail: tl, content: c, path: "/p/x3/f"},
+	}
+
+	super, dirs := treeOf(t, recs)
+
+	got := groupPaths(collectTreeGroups(dirs, super, everyPathExists, nil))
 
 	want := [][]string{{"/p/x1", "/p/x2"}}
 	if !slices.EqualFunc(got, want, slices.Equal) {
@@ -450,10 +492,159 @@ func TestCollectTreeGroupsDifferingParents(t *testing.T) {
 
 	super, dirs := treeOf(t, recs)
 
-	got := groupPaths(collectTreeGroups(dirs, super, nil))
+	got := groupPaths(collectTreeGroups(dirs, super, everyPathExists, nil))
 
 	want := [][]string{{"/p/a/x", "/q/b/x"}}
 	if !slices.EqualFunc(got, want, slices.Equal) {
 		t.Fatalf("groups = %v, want %v", got, want)
 	}
 }
+
+// TestCollectTreeGroupsChecksOnlyReportedCopies checks that trees asks
+// whether a directory is on disk only for the members of the groups it
+// returns. It never asks about /a/proj/sub, which lies inside a copy
+// and whose group the group of /a/proj implies.
+func TestCollectTreeGroupsChecksOnlyReportedCopies(t *testing.T) {
+	t.Parallel()
+
+	f, g, u := testHash("f"), testHash("g"), testHash("u")
+	recs := []scanRec{
+		{size: 10, head: f, tail: f, content: f, path: "/a/proj/f"},
+		{size: 20, head: g, tail: g, content: g, path: "/a/proj/sub/g"},
+		{size: 10, head: f, tail: f, content: f, path: "/b/proj/f"},
+		{size: 20, head: g, tail: g, content: g, path: "/b/proj/sub/g"},
+		// /a lacks this file, so /a and /b are no copies of each other.
+		{size: 30, head: u, tail: u, content: u, path: "/b/lonely"},
+	}
+
+	super, dirs := treeOf(t, recs)
+
+	var checked []string
+
+	exists := func(path string) bool {
+		checked = append(checked, path)
+
+		return true
+	}
+
+	got := groupPaths(collectTreeGroups(dirs, super, exists, nil))
+
+	want := [][]string{{"/a/proj", "/b/proj"}}
+	if !slices.EqualFunc(got, want, slices.Equal) {
+		t.Fatalf("groups = %v, want %v", got, want)
+	}
+
+	slices.Sort(checked)
+
+	if !slices.Equal(checked, want[0]) {
+		t.Errorf("directories checked on disk = %q, want %q",
+			checked, want[0])
+	}
+}
+
+// TestCollectTreeGroupsDropsGroupLeftWithOneCopy checks that a group of
+// two copies, one of them gone, is not returned. If kept, it would
+// write no row, but the summary line would count it.
+func TestCollectTreeGroupsDropsGroupLeftWithOneCopy(t *testing.T) {
+	t.Parallel()
+
+	f := testHash("f")
+	recs := []scanRec{
+		{size: 10, head: f, tail: f, content: f, path: "/c/kept/f"},
+		{size: 10, head: f, tail: f, content: f, path: "/c/gone/f"},
+	}
+
+	super, dirs := treeOf(t, recs)
+
+	exists := func(path string) bool { return path != "/c/gone" }
+
+	got := groupPaths(collectTreeGroups(dirs, super, exists, nil))
+	if len(got) != 0 {
+		t.Errorf("groups = %v, want none", got)
+	}
+}
+
+// TestCollectTreeGroupsKeepsGroupLeftWithTwoCopies checks that a group
+// of three copies, one of them gone, is returned with the other two.
+func TestCollectTreeGroupsKeepsGroupLeftWithTwoCopies(t *testing.T) {
+	t.Parallel()
+
+	f := testHash("f")
+	recs := []scanRec{
+		{size: 10, head: f, tail: f, content: f, path: "/d/kept1/f"},
+		{size: 10, head: f, tail: f, content: f, path: "/d/gone/f"},
+		{size: 10, head: f, tail: f, content: f, path: "/d/kept2/f"},
+	}
+
+	super, dirs := treeOf(t, recs)
+
+	exists := func(path string) bool { return path != "/d/gone" }
+
+	got := groupPaths(collectTreeGroups(dirs, super, exists, nil))
+
+	want := [][]string{{"/d/kept1", "/d/kept2"}}
+	if !slices.EqualFunc(got, want, slices.Equal) {
+		t.Errorf("groups = %v, want %v", got, want)
+	}
+}
+
+// TestReclaimableBytesCountsNestedDupeOnce checks that a dupe tree
+// inside another dupe tree adds nothing to the reclaimable bytes. /B/x
+// lies in /B, so the total adds the sizes of /B and /C/x, 1500 + 1000.
+func TestReclaimableBytesCountsNestedDupeOnce(t *testing.T) {
+	t.Parallel()
+
+	fh, ft, fc := testHash("fh"), testHash("ft"), testHash("fc")
+	gh, gt, gc := testHash("gh"), testHash("gt"), testHash("gc")
+	recs := []scanRec{
+		{size: 1000, head: fh, tail: ft, content: fc, path: "/A/x/f"},
+		{size: 500, head: gh, tail: gt, content: gc, path: "/A/y/g"},
+		{size: 1000, head: fh, tail: ft, content: fc, path: "/B/x/f"},
+		{size: 500, head: gh, tail: gt, content: gc, path: "/B/y/g"},
+		{size: 1000, head: fh, tail: ft, content: fc, path: "/C/x/f"},
+	}
+
+	super, dirs := treeOf(t, recs)
+	dupes := collectTreeGroups(dirs, super, everyPathExists, nil)
+
+	wantGroups := [][]string{{"/A", "/B"}, {"/A/x", "/B/x", "/C/x"}}
+	if got := groupPaths(dupes); !slices.EqualFunc(got, wantGroups,
+		slices.Equal) {
+		t.Fatalf("groups = %v, want %v", got, wantGroups)
+	}
+
+	if got := reclaimableBytes(dupes); got != 2500 {
+		t.Errorf("reclaimableBytes = %d, want 2500", got)
+	}
+}
+
+// TestReclaimableBytesCountsDupeInsideGrandparentDupeOnce checks that a
+// dupe tree adds nothing when a dupe tree above its parent holds it.
+// /B/m/x lies in /B, and /B/m is no dupe, since the group of /A and /B
+// implies that of /A/m and /B/m. The total adds the sizes of /B and
+// /C/x, 1300 + 1000.
+func TestReclaimableBytesCountsDupeInsideGrandparentDupeOnce(t *testing.T) {
+	t.Parallel()
+
+	f, w := testHash("f"), testHash("w")
+	recs := []scanRec{
+		{size: 1000, head: f, tail: f, content: f, path: "/A/m/x/f"},
+		{size: 300, head: w, tail: w, content: w, path: "/A/m/w"},
+		{size: 1000, head: f, tail: f, content: f, path: "/B/m/x/f"},
+		{size: 300, head: w, tail: w, content: w, path: "/B/m/w"},
+		{size: 1000, head: f, tail: f, content: f, path: "/C/x/f"},
+	}
+
+	super, dirs := treeOf(t, recs)
+	dupes := collectTreeGroups(dirs, super, everyPathExists, nil)
+
+	wantGroups := [][]string{{"/A", "/B"}, {"/A/m/x", "/B/m/x", "/C/x"}}
+	if got := groupPaths(dupes); !slices.EqualFunc(got, wantGroups,
+		slices.Equal) {
+		t.Fatalf("groups = %v, want %v", got, wantGroups)
+	}
+
+	if got := reclaimableBytes(dupes); got != 2300 {
+		t.Errorf("reclaimableBytes = %d, want 2300", got)
+	}
+}