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

@@ -22,9 +22,8 @@ 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` work from the database and
-can run at any time. `report` and `trees` leave out a copy that was deleted
-after the scan. `dwim` scans `/` and then prints the `trees` report, for a first
-look at a new machine with one command.
+can run at any time. `dwim` scans `/` and then prints the `trees` report, for a
+first look at a new machine with one command.
 
 ## Getting Started
 
@@ -255,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
-  report.
+- `dwim` scans `/`, then prints the duplicate-tree report.
 
 ```
 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
 ```
@@ -293,20 +291,20 @@ 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
-  lists the trees. It also sets how many files `scan` reads at once while it
-  hashes them. The default is the number of CPUs. `N` must be at least 1. A
-  smaller value is a usage error, reported in one line on stderr with exit 2
-  before anything is scanned.
-- `-x`, `--one-file-system` (`scan`) keeps the walk of each operand out of
-  directories on other filesystems, as the same flag does for `du` and `rsync`.
-  By default the walk also enters directories on other filesystems.
-- `--no-default-excludes` (`scan`) lets the walk enter the default excludes.
-  Those are the system and temporary directories the walk otherwise leaves out,
-  such as `/var/tmp` on Linux (see "Rules for the walk").
-- `--exclude PATH` (`scan`) 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
+- `--workers N` (`scan`, `dwim`) sets how many directories `scan` reads at once
+  while it lists the trees. It also sets how many files `scan` reads at once
+  while it hashes them. The default is the number of CPUs. `N` must be at
+  least 1. A smaller value is a usage error, reported in one line on stderr with
+  exit 2 before anything is scanned.
+- `-x`, `--one-file-system` (`scan`, `dwim`) keeps the walk of each operand out
+  of directories on other filesystems, as the same flag does for `du` and
+  `rsync`. By default the walk also enters directories on other filesystems.
+- `--no-default-excludes` (`scan`, `dwim`) lets the walk enter the default
+  excludes. Those are the system and temporary directories the walk otherwise
+  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
@@ -317,8 +315,10 @@ The reference below is also the program's specification.
 - `--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
-  default excludes of the system it runs on, and the filesystem types the walk
+  and exits 0. It writes nothing to stdout. The help of `sfdupes` and of `scan`
+  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
@@ -848,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
@@ -857,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
-its own. Like `scan`, it should run as root, so that it can read every file.
+duplicate trees in one command. It takes no positional arguments. Like `scan`,
+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
-excludes and crosses into other filesystems. `--workers` keeps its default. The
+`dwim` takes these flags of `scan`, with the same meaning (see "Settings"):
+
+- `--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:
 

TODO.md

@@ -29,6 +29,19 @@
 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,

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,
-		false, nil)
+	opts := scanOptions{workers: walkCancelWorkers}
+
+	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,
-			false, false, nil)
+		err = runScan(cancelledContext(t), []string{dir}, opts)
 	}()
 
 	awaitReturn(t, done, "runScan")
@@ -410,8 +410,7 @@ func TestRunScanInterrupted(t *testing.T) {
 			got, before)
 	}
 
-	err = runScan(t.Context(), []string{dir}, walkCancelWorkers, false,
-		false, nil)
+	err = runScan(t.Context(), []string{dir}, opts)
 	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, nil)
+		scanOptions{workers: walkCancelWorkers})
 	if !errors.Is(err, errInterrupted) {
 		t.Fatalf("runScan interrupted mid-hash = %v, want %v",
 			err, errInterrupted)

internal/sfdupes/cli.go

@@ -32,17 +32,79 @@ 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
-// below 1.
+// errWorkersBelowOne is the usage error for a --workers value below 1.
 var errWorkersBelowOne = errors.New("--workers must be at least 1")
 
-// errEmptyExcludeValue is the usage error for an empty scan --exclude
-// value, as from --exclude "$DIR" with DIR unset. Taken as a path, it
+// 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")
 
@@ -193,76 +255,116 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 		}),
 	}
 
-	dwimCmd := &cobra.Command{
-		Use:   cmdDwim,
-		Short: "Scan / with the default excludes, then print the duplicate-tree report",
-		Args:  cobra.NoArgs,
-		RunE: runE(func(ctx context.Context, _ []string) error {
-			return runDwim(ctx, "/", stdout)
-		}),
-	}
+	root.Long = root.Short + ".\n\n" + databaseHelp
+	reportCmd.Long = reportCmd.Short + ".\n\n" + reportHelp
+	treesCmd.Long = treesCmd.Short + ".\n\n" + treesHelp
+	infoCmd.Long = infoCmd.Short + ".\n\n" + infoHelp
 
-	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,
-// --no-default-excludes and --exclude flags. Its help lists the default
-// excludes of the system it runs on, and the filesystem types it never
-// records anything on.
+// scanOptions holds the values of the flags that scan and dwim share:
+// --workers, -x, --no-default-excludes and --exclude.
+type scanOptions struct {
+	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 (
-		scanWorkers           int
-		scanOneFS             bool
-		scanNoDefaultExcludes bool
-		scanExclude           []string
-	)
+	var opts scanOptions
 
 	short := "Walk trees and synchronize the scan database"
 
 	scanCmd := &cobra.Command{
-		Use: cmdScan + " [--workers N] [-x] [--no-default-excludes] " +
-			"[--exclude PATH]... PATH...",
+		Use: cmdScan + " " + scanFlagsUsage + " PATH...",
 		// The Use line already names every flag, so cobra must not
 		// append its generic "[flags]" to it.
 		DisableFlagsInUseLine: true,
 		Short:                 short,
-		Long:                  short + ".\n\n" + defaultExcludesHelp(runtime.GOOS),
-		Args:                  cobra.MinimumNArgs(1),
-		PreRunE: func(cmd *cobra.Command, _ []string) error {
-			err := checkScanWorkers(cmd, scanWorkers)
-			if err != nil {
-				return err
-			}
-
-			return rejectEmptyExcludeValue(cmd, scanExclude)
-		},
+		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,
-				scanNoDefaultExcludes, scanExclude)
+			return runScan(ctx, args, opts)
 		}),
 	}
-	scanCmd.Flags().IntVar(&scanWorkers, "workers", runtime.NumCPU(),
-		"concurrent workers for the walk and hash phases")
-	scanCmd.Flags().BoolVarP(&scanOneFS, "one-file-system", "x", false,
-		"do not cross filesystem boundaries")
-	scanCmd.Flags().BoolVar(&scanNoDefaultExcludes, "no-default-excludes",
-		false, "enter the default excludes, the paths listed above")
-	// A string array, not a slice, so a comma in a path is not a
-	// separator.
-	scanCmd.Flags().StringArrayVar(&scanExclude, "exclude", nil,
-		"never enter or record `PATH` or anything below it; repeatable")
+	addScanFlags(scanCmd, &opts)
 
 	return scanCmd
 }
 
-// checkScanWorkers rejects a scan --workers value below 1. That is a
-// usage error reported in one line: cobra prints the returned message
-// without the usage text, and run exits 2.
+// newDwimCommand builds the dwim subcommand, which takes the scan flags
+// with the meaning they have for scan. Its help says what dwim runs,
+// 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
@@ -273,7 +375,7 @@ func checkScanWorkers(cmd *cobra.Command, workers int) error {
 	return fmt.Errorf("%w, got %d", errWorkersBelowOne, workers)
 }
 
-// rejectEmptyExcludeValue rejects an empty scan --exclude value. That
+// 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, "") {

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,8 +576,8 @@ func TestRunNamesDefaultDatabase(t *testing.T) {
 	}{
 		cmdScan: {
 			run: func() error {
-				return runScan(t.Context(), []string{missing}, 1, false, false,
-					nil)
+				return runScan(t.Context(), []string{missing},
+					scanOptions{workers: 1})
 			},
 			want: scanWant,
 		},
@@ -662,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 {
@@ -693,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
@@ -754,6 +760,73 @@ func TestRunScanUsageLine(t *testing.T) {
 	}
 }
 
+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) {
 	t.Parallel()
 

internal/sfdupes/dwim.go

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

@@ -254,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/scan.go

@@ -98,17 +98,16 @@ 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
-// scan command rejects anything less. Before the lock is taken, the
-// scan lists the filesystems that are not persistent, on which the walk
-// records nothing; unless noDefaultExcludes is set, the walk does not
-// enter the default excludes either. The walk neither enters nor
-// records the paths in excludePaths, the --exclude values; an operand
-// at or below one is a fatal error. Once the database is open, the scan
-// notes its files, which the walk passes over.
-func runScan(ctx context.Context, roots []string, workers int,
-	oneFS, noDefaultExcludes bool, excludePaths []string,
-) error {
+// reached, and returns errInterrupted. opts.workers must be at least 1;
+// the scan and dwim commands reject anything less. Before the lock is
+// taken, the scan lists the filesystems that are not persistent, on
+// which the walk records nothing; unless opts.noDefaultExcludes is set,
+// the walk does not enter the default excludes either. The walk neither
+// enters nor records the paths in opts.excludePaths, the --exclude
+// values; an operand at or below one is a fatal error. Once the
+// database is open, the scan notes its files, which the walk passes
+// over.
+func runScan(ctx context.Context, roots []string, opts scanOptions) error {
 	dbPath, source, err := databasePath()
 	if err != nil {
 		return err
@@ -123,7 +122,7 @@ func runScan(ctx context.Context, roots []string, workers int,
 
 	var rules walkRules
 
-	rules.excludePaths, err = excludePathInodes(excludePaths)
+	rules.excludePaths, err = excludePathInodes(opts.excludePaths)
 	if err != nil {
 		return fmt.Errorf("--exclude: %w", err)
 	}
@@ -138,7 +137,7 @@ func runScan(ctx context.Context, roots []string, workers int,
 		return fmt.Errorf("list the mounted filesystems: %w", err)
 	}
 
-	if !noDefaultExcludes {
+	if !opts.noDefaultExcludes {
 		rules.defaultExcludes = defaultExcludes(runtime.GOOS)
 	}
 
@@ -167,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)
 	}

internal/sfdupes/scan_test.go

@@ -2196,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",

internal/sfdupes/trees.go

@@ -101,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()
 
@@ -112,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
 }
@@ -146,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)
-// and the bytes they could reclaim.
+// go through prog's writer. It returns the number of rows (dupe trees).
 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:] {
@@ -169,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()
@@ -181,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

internal/sfdupes/trees_test.go

@@ -313,7 +313,7 @@ func TestWriteTreeGroupsOnTerminal(t *testing.T) {
 		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()
 
@@ -587,3 +587,64 @@ func TestCollectTreeGroupsKeepsGroupLeftWithTwoCopies(t *testing.T) {
 		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)
+	}
+}