Add sfdupes dwim: scan / then print duplicate trees (closes #154)

sfdupes dwim, as sneak ordered: with no arguments it runs what scan / runs with no flags, default excludes on, then what trees runs, printing the duplicate trees largest first on stdout. Its last line, on stderr, says that sfdupes trees prints the report again. It needs no setup beyond what scan creates. SIGINT or SIGTERM during the scan stops it as it stops scan, exit 1, with no report; during the report a signal ends it at once, as it ends trees. A positional argument is a usage error, exit 2.

Model: opus-5-5

db.go

@@ -146,33 +146,44 @@ var errHashSize = errors.New("hash is not 32 bytes")
 
 // databasePath resolves the database location: SFDUPES_DATABASE when
 // set and non-empty, the compiled-in default otherwise. It returns the
-// path, with the working directory, its symlinks resolved, put in front
-// of it when it is relative, and where the path came from, "default" or
-// "from SFDUPES_DATABASE", for the line each subcommand prints first on
-// stderr.
+// path, made absolute by absolutePath, and where the path came from,
+// "default" or "from SFDUPES_DATABASE", for the line each subcommand
+// prints first on stderr.
 func databasePath() (string, string, error) {
 	path, source := defaultDatabasePath, "default"
 	if p := os.Getenv(databaseEnv); p != "" {
 		path, source = p, "from "+databaseEnv
 	}
 
-	if filepath.IsAbs(path) {
-		return path, source, nil
-	}
-
-	// The working directory as the kernel reports it, with no symlink
-	// in it, as README "Database" says. os.Getwd may return PWD
-	// instead, which can name it through a symlink.
-	wd, err := unix.Getwd()
+	abs, err := absolutePath(path)
 	if err != nil {
 		return "", "", fmt.Errorf("resolve database path %s: %w", path, err)
 	}
 
-	// Not filepath.Abs or filepath.Join: they clean the path, which
-	// drops each ".." together with the directory name before it. When
-	// that directory is a symlink, the cleaned path names another file.
+	return abs, source, nil
+}
+
+// absolutePath returns path unchanged when it is absolute, and
+// otherwise the working directory, a "/" and path. The working
+// directory is the one the kernel reports, with no symlink in it;
+// os.Getwd may return PWD instead, which can name it through a symlink.
+// The result is not cleaned, as filepath.Abs and filepath.Join would
+// clean it. Cleaning drops each ".." together with the directory name
+// before it. When that name is a symlink, the cleaned path names
+// another file than the one the system reaches by following the symlink
+// first.
+func absolutePath(path string) (string, error) {
+	if filepath.IsAbs(path) {
+		return path, nil
+	}
+
+	wd, err := unix.Getwd()
+	if err != nil {
+		return "", err
+	}
+
 	// The working directory ends in "/" only when it is the root.
-	return strings.TrimSuffix(wd, "/") + "/" + path, source, nil
+	return strings.TrimSuffix(wd, "/") + "/" + path, nil
 }
 
 // createDatabaseDirectory creates the directory the database at path

dwim.go

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

dwim_test.go

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

exclude_test.go

@@ -17,7 +17,9 @@ import (
 func TestDefaultExcludes(t *testing.T) {
 	t.Parallel()
 
-	// README "Rules for the walk": each system's list.
+	// README "Rules for the walk": the Linux and macOS lists, and none
+	// on any other system. The Windows list exists in the code only: the
+	// binary does not build for Windows, so the README leaves it out.
 	cases := map[string][]string{
 		goosLinux: {"/proc", "/sys", "/dev", "/run", "/tmp", "/var/tmp"},
 		goosDarwin: {
@@ -284,7 +286,7 @@ func TestRunScanTempDirOperand(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
-	dir := t.TempDir()
+	dir := realTempDir(t)
 	if !underAnyRoot(dir, defaultExcludes(runtime.GOOS)) {
 		t.Skip(dir + " is not inside a default exclude")
 	}

main.go

@@ -14,6 +14,7 @@
 //	sfdupes report > dupes.tsv
 //	sfdupes trees > dupetrees.tsv
 //	sfdupes info
+//	sfdupes dwim
 //	sfdupes --version
 //
 // See README.md for the complete specification.
@@ -45,6 +46,7 @@ const (
 	cmdReport = "report"
 	cmdTrees  = "trees"
 	cmdInfo   = "info"
+	cmdDwim   = "dwim"
 )
 
 // errNoSubcommand is returned by the root command when it is invoked
@@ -96,8 +98,8 @@ func main() {
 // exit code. It is the program's single exit point: the subcommands
 // return their errors instead of exiting, so every deferred cleanup —
 // above all closing the database, which checkpoints the SQLite WAL —
-// runs before the process ends. The report, trees and info subcommands
-// write their data to stdout.
+// runs before the process ends. The report, trees, info and dwim
+// subcommands write their data to stdout.
 func run(args []string, stdout, stderr io.Writer) int {
 	// A nil slice makes cobra fall back to os.Args, which would let a
 	// test binary's own flags reach the command tree.
@@ -201,7 +203,16 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 		}),
 	}
 
-	root.AddCommand(newScanCommand(), reportCmd, treesCmd, infoCmd)
+	dwimCmd := &cobra.Command{
+		Use:   cmdDwim,
+		Short: "Scan / with the default excludes, then print the duplicate-tree report",
+		Args:  cobra.NoArgs,
+		RunE: runE(func(ctx context.Context, _ []string) error {
+			return runDwim(ctx, "/", stdout)
+		}),
+	}
+
+	root.AddCommand(newScanCommand(), reportCmd, treesCmd, infoCmd, dwimCmd)
 
 	return root
 }

main_test.go

@@ -14,6 +14,8 @@ import (
 	"strconv"
 	"strings"
 	"testing"
+
+	"golang.org/x/sys/unix"
 )
 
 // usageMarker is the first line of cobra's usage text, which a usage
@@ -394,7 +396,7 @@ func TestRunNamesRelativeDatabase(t *testing.T) {
 }
 
 func TestRunUsesDatabaseThroughSymlinkedDirectory(t *testing.T) {
-	// README §Database: the path names the file exactly. With link a
+	// README §Settings: the path names the file exactly. With link a
 	// symlink to the directory real/sub, link/../db.sqlite names
 	// real/db.sqlite, not db.sqlite beside link. Every subcommand must
 	// use that file, relative or absolute, and its first line must name
@@ -620,6 +622,7 @@ func TestRunUsageErrors(t *testing.T) {
 		"report with args":   {[]string{cmdReport, "x"}, usageMarker},
 		"trees with args":    {[]string{cmdTrees, "x"}, usageMarker},
 		"info with args":     {[]string{cmdInfo, "x"}, usageMarker},
+		"dwim with args":     {[]string{cmdDwim, "x"}, usageMarker},
 		"unknown flag":       {[]string{cmdScan, "--nope", "/"}, usageMarker},
 		"unknown subcommand": {[]string{"nope"}, "unknown command"},
 	}
@@ -649,7 +652,7 @@ func TestRunUsageErrors(t *testing.T) {
 }
 
 func TestRunScanRejectsWorkersBelowOne(t *testing.T) {
-	// README §scan mode: --workers below 1 is a usage error reported in
+	// README §Settings: --workers below 1 is a usage error reported in
 	// one line on stderr, before the scan opens the database.
 	for _, workers := range []string{"0", "-1"} {
 		t.Run(workers, func(t *testing.T) {
@@ -687,8 +690,8 @@ func TestRunScanRejectsWorkersBelowOne(t *testing.T) {
 func TestRunHelp(t *testing.T) {
 	t.Parallel()
 
-	// README §Subcommands: help goes to stderr, exits 0, and leaves
-	// stdout empty.
+	// README §Settings: help goes to stderr, exits 0, and leaves stdout
+	// empty.
 	cases := [][]string{{"--help"}, {"-h"}, {cmdScan, "--help"}}
 
 	for _, args := range cases {
@@ -714,8 +717,8 @@ func TestRunHelp(t *testing.T) {
 func TestRunVersion(t *testing.T) {
 	t.Parallel()
 
-	// README §Subcommands: the version is one line on stdout, with
-	// nothing on stderr, and exits 0.
+	// README §Settings: the version is one line on stdout, with nothing
+	// on stderr, and exits 0.
 	info, _ := debug.ReadBuildInfo()
 
 	for _, arg := range []string{"--version", "-v"} {
@@ -774,8 +777,8 @@ func TestBuildVersion(t *testing.T) {
 func TestRunVersionWriteFailureIsFatal(t *testing.T) {
 	t.Parallel()
 
-	// README §Error handling: a stdout write failure exits 1, reported
-	// in one line on stderr.
+	// README §Error handling: a failed write to stdout is a fatal error,
+	// exit 1, reported on stderr starting with "sfdupes:".
 	var stderr bytes.Buffer
 
 	code := run([]string{"--version"}, failingWriter{}, &stderr)
@@ -797,7 +800,7 @@ func TestRunVersionWriteFailureIsFatal(t *testing.T) {
 func scanFixture(t *testing.T) []string {
 	t.Helper()
 
-	dir := t.TempDir()
+	dir := realTempDir(t)
 
 	dupes := []string{
 		writeFile(t, dir, "one/a.bin", pattern(1, 300)),
@@ -867,7 +870,7 @@ func TestRunScanSucceedsDespiteWarnings(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
-	dir := t.TempDir()
+	dir := realTempDir(t)
 	writeFile(t, dir, "a.bin", pattern(1, 300))
 
 	// Same size as a.bin, so the scan reads it, and the read fails.
@@ -895,58 +898,278 @@ func TestRunScanSucceedsDespiteWarnings(t *testing.T) {
 	assertNoSidecars(t, path)
 }
 
-func TestRunScanSkipsSymlinkOperand(t *testing.T) {
-	path := testDBPath(t)
-	t.Setenv(databaseEnv, path)
+// realTempDir returns a new temporary directory by its real path, so
+// tests hold where the temporary directory is reached through a
+// symlink.
+func realTempDir(t *testing.T) string {
+	t.Helper()
 
-	dir := t.TempDir()
-	writeFile(t, dir, "target/sub/f", pattern(1, 10))
-
-	link := filepath.Join(dir, "link")
-
-	err := os.Symlink(filepath.Join(dir, "target"), link)
+	dir, err := filepath.EvalSymlinks(t.TempDir())
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	// Scanning a directory through the symlink stores a record beneath
-	// the symlink's own path for a file beneath its target.
-	scanOK(t, filepath.Join(link, "sub"))
-
-	assertOperandSkipped(t, path, link, "symlink",
-		filepath.Join(link, "sub", "f"))
+	return dir
 }
 
+// symlink creates link pointing at target.
+func symlink(t *testing.T, target, link string) {
+	t.Helper()
+
+	err := os.Symlink(target, link)
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+// TestRunScanFollowsSymlinkOperand scans link, a symlink to target.
+// The operand is scanned at its real path, and its file is recorded
+// there.
+func TestRunScanFollowsSymlinkOperand(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := realTempDir(t)
+	f := writeFile(t, dir, "target/sub/f", pattern(1, 10))
+
+	link := filepath.Join(dir, "link")
+	symlink(t, filepath.Join(dir, "target"), link)
+
+	stderr := scanOK(t, link)
+
+	summary := "scan: 1 files seen (1 added, 0 updated, 0 removed, " +
+		"0 unchanged), 0 skipped\n"
+	if !strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q", stderr, summary)
+	}
+
+	if got := storedPaths(t, path); !slices.Equal(got, []string{f}) {
+		t.Errorf("records = %q, want %q", got, []string{f})
+	}
+}
+
+// TestRunScanWalksOperandUnderSymlinkOperand scans link and link/sub,
+// with link a symlink to target. Both resolve under target, so
+// target/sub is walked once, as part of target.
 func TestRunScanWalksOperandUnderSymlinkOperand(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
-	dir := t.TempDir()
-	writeFile(t, dir, "target/sub/f", pattern(1, 10))
+	dir := realTempDir(t)
+	f := writeFile(t, dir, "target/sub/f", pattern(1, 10))
 
 	link := filepath.Join(dir, "link")
+	symlink(t, filepath.Join(dir, "target"), link)
 
-	err := os.Symlink(filepath.Join(dir, "target"), link)
+	stderr := scanOK(t, link, filepath.Join(link, "sub"))
+
+	summary := "scan: 1 files seen (1 added, 0 updated, 0 removed, " +
+		"0 unchanged), 0 skipped\n"
+	if !strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q", stderr, summary)
+	}
+
+	if got := storedPaths(t, path); !slices.Equal(got, []string{f}) {
+		t.Errorf("records = %q, want %q", got, []string{f})
+	}
+}
+
+// TestRunScanWalksSymlinkedOperandBelowOperand is the case of
+// https://git.eeqj.de/sneak/sfdupes/issues/144: scan dir dir/link/sub,
+// with dir/link a symlink to a directory outside dir. The walk of dir
+// does not follow link, so dir/link/sub is walked on its own at its
+// real path, and the record an earlier scan stored there survives.
+func TestRunScanWalksSymlinkedOperandBelowOperand(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := realTempDir(t)
+	a := writeFile(t, dir, "a", pattern(1, 10))
+
+	outside := realTempDir(t)
+	f := writeFile(t, outside, "sub/f", pattern(2, 10))
+
+	symlink(t, outside, filepath.Join(dir, "link"))
+
+	scanOK(t, filepath.Join(outside, "sub"))
+
+	stderr := scanOK(t, dir, filepath.Join(dir, "link", "sub"))
+
+	summary := "scan: 2 files seen (1 added, 0 updated, 0 removed, " +
+		"1 unchanged), 0 skipped\n"
+	if !strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q", stderr, summary)
+	}
+
+	want := []string{a, f}
+	slices.Sort(want)
+
+	if got := storedPaths(t, path); !slices.Equal(got, want) {
+		t.Errorf("records = %q, want %q", got, want)
+	}
+}
+
+// TestRunScanDropsSymlinkOperandInsideOperand scans dir and link, with
+// link, outside dir, a symlink to dir/real. link resolves inside dir,
+// so it is dropped as covered by dir, and its file is recorded once.
+func TestRunScanDropsSymlinkOperandInsideOperand(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := realTempDir(t)
+	f := writeFile(t, dir, "real/f", pattern(1, 10))
+
+	link := filepath.Join(realTempDir(t), "link")
+	symlink(t, filepath.Join(dir, "real"), link)
+
+	stderr := scanOK(t, dir, link)
+
+	summary := "scan: 1 files seen (1 added, 0 updated, 0 removed, " +
+		"0 unchanged), 0 skipped\n"
+	if !strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q", stderr, summary)
+	}
+
+	if got := storedPaths(t, path); !slices.Equal(got, []string{f}) {
+		t.Errorf("records = %q, want %q", got, []string{f})
+	}
+}
+
+// TestRunScanDanglingSymlinkOperandIsFatal scans a valid directory and
+// a symlink whose target does not exist. The scan fails with exit 1 and
+// an error naming the symlink as given, before it walks anything, so no
+// database is created.
+func TestRunScanDanglingSymlinkOperandIsFatal(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := realTempDir(t)
+	writeFile(t, dir, "f", pattern(1, 10))
+
+	dangling := filepath.Join(realTempDir(t), "dangling")
+	symlink(t, filepath.Join(dir, "missing"), dangling)
+
+	stdout := captureStdout(t)
+
+	var stderr bytes.Buffer
+
+	code := run([]string{cmdScan, dir, dangling}, os.Stdout, &stderr)
+	if code != exitFatal {
+		t.Errorf("run(scan %s %s) = %d, want %d", dir, dangling, code,
+			exitFatal)
+	}
+
+	assertFatalOutput(t, stderr.String(), stdout())
+
+	want := "sfdupes: resolve " + dangling + ": "
+	if !strings.Contains(stderr.String(), want) {
+		t.Errorf("stderr = %q, want %q", stderr.String(), want)
+	}
+
+	_, err := os.Stat(path)
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("database: stat error %v, want it missing", err)
+	}
+}
+
+// TestRunScanFromSymlinkedWorkingDirectoryRecordsRealPath runs scan .
+// after a cd through home/proj, a symlink to data/proj. The file is
+// recorded under data/proj, its real path.
+func TestRunScanFromSymlinkedWorkingDirectoryRecordsRealPath(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := realTempDir(t)
+	f := writeFile(t, dir, "data/proj/f", pattern(1, 10))
+
+	err := os.Mkdir(filepath.Join(dir, "home"), 0o750)
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	// link is dropped as a symlink, but link/sub must still be scanned,
-	// not dropped as lying under link.
-	scanOK(t, link, filepath.Join(link, "sub"))
+	symlink(t, filepath.Join(dir, "data", "proj"),
+		filepath.Join(dir, "home", "proj"))
 
-	db, err := openDB(path, reportParams)
+	// t.Chdir also sets PWD to the path through the symlink, as a
+	// shell does after cd.
+	t.Chdir(filepath.Join(dir, "home", "proj"))
+
+	scanOK(t, ".")
+
+	if got := storedPaths(t, path); !slices.Equal(got, []string{f}) {
+		t.Errorf("records = %q, want %q", got, []string{f})
+	}
+}
+
+// TestRunScanFollowsSymlinkBeforeDotDot scans a path with a ".." after
+// home/proj, a symlink to data/proj: home/proj/.. from dir, and .. after
+// a cd through home/proj. As with realpath, the ".." counts from
+// data/proj, so data is scanned and home is not.
+func TestRunScanFollowsSymlinkBeforeDotDot(t *testing.T) {
+	for _, tc := range []struct{ wd, operand string }{
+		{"", "home/proj/.."},
+		{"home/proj", ".."},
+	} {
+		t.Run(tc.operand, func(t *testing.T) {
+			path := testDBPath(t)
+			t.Setenv(databaseEnv, path)
+
+			dir := realTempDir(t)
+			f := writeFile(t, dir, "data/proj/f", pattern(1, 10))
+			g := writeFile(t, dir, "data/g", pattern(2, 10))
+			writeFile(t, dir, "home/h", pattern(3, 10))
+			symlink(t, filepath.Join(dir, "data", "proj"),
+				filepath.Join(dir, "home", "proj"))
+
+			// t.Chdir also sets PWD to the path given, as a shell does
+			// after cd.
+			t.Chdir(filepath.Join(dir, tc.wd))
+
+			scanOK(t, tc.operand)
+
+			want := []string{f, g}
+			slices.Sort(want)
+
+			if got := storedPaths(t, path); !slices.Equal(got, want) {
+				t.Errorf("records = %q, want %q", got, want)
+			}
+		})
+	}
+}
+
+// TestRunScanSkipsSymlinkToFIFOOperand scans link, a symlink to a FIFO.
+// The scan warns about the FIFO by its real path, counts it as skipped,
+// and exits 0.
+func TestRunScanSkipsSymlinkToFIFOOperand(t *testing.T) {
+	t.Setenv(databaseEnv, testDBPath(t))
+
+	dir := realTempDir(t)
+	fifo := filepath.Join(dir, "fifo")
+
+	err := unix.Mkfifo(fifo, 0o600)
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	t.Cleanup(func() { _ = db.Close() })
+	link := filepath.Join(dir, "link")
+	symlink(t, fifo, link)
 
-	recordByPath(t, dbRecords(t, db), filepath.Join(link, "sub", "f"))
+	stderr := scanOK(t, link)
+
+	warning := "walk " + fifo + ": skipping FIFO operand\n"
+	if !strings.Contains(stderr, warning) {
+		t.Errorf("stderr = %q, want %q", stderr, warning)
+	}
+
+	summary := "scan: 0 files seen (0 added, 0 updated, 0 removed, " +
+		"0 unchanged), 1 skipped\n"
+	if !strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q", stderr, summary)
+	}
 }
 
 func TestRunScanSkipsZFSOperand(t *testing.T) {
-	zfs := filepath.Join(t.TempDir(), ".zfs")
+	zfs := filepath.Join(realTempDir(t), ".zfs")
 	f := writeFile(t, zfs, "snapshot/hourly/f", pattern(1, 10))
 
 	// No scan records a file inside a .zfs directory, so the record
@@ -997,7 +1220,7 @@ func TestRunScanSkipsOperandInsideZFS(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
-	dir := t.TempDir()
+	dir := realTempDir(t)
 	hourly := filepath.Join(dir, ".zfs", "snapshot", "hourly")
 	writeFile(t, hourly, "f", pattern(1, 10))
 	f := writeFile(t, dir, "f", pattern(2, 10))
@@ -1041,23 +1264,19 @@ func TestRunScanSkipsOperandInsideZFS(t *testing.T) {
 
 // TestRunScanSkipsOperandThroughSymlinkIntoZFS scans snaps/daily, where
 // snaps is a symlink to pool/.zfs/snapshot. The operand is warned about
-// by the path given, counted as skipped, and not walked.
+// by its real path, counted as skipped, and not walked.
 func TestRunScanSkipsOperandThroughSymlinkIntoZFS(t *testing.T) {
 	t.Setenv(databaseEnv, testDBPath(t))
 
-	dir := t.TempDir()
+	dir := realTempDir(t)
 	writeFile(t, dir, "pool/.zfs/snapshot/daily/f", pattern(1, 10))
 
 	snaps := filepath.Join(dir, "snaps")
+	symlink(t, filepath.Join(dir, "pool", ".zfs", "snapshot"), snaps)
 
-	err := os.Symlink(filepath.Join(dir, "pool", ".zfs", "snapshot"), snaps)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	daily := filepath.Join(snaps, "daily")
-	stderr := scanOK(t, daily)
+	stderr := scanOK(t, filepath.Join(snaps, "daily"))
 
+	daily := filepath.Join(dir, "pool", ".zfs", "snapshot", "daily")
 	warning := "walk " + daily + ": skipping operand inside a .zfs directory\n"
 	summary := "scan: 0 files seen (0 added, 0 updated, 0 removed, " +
 		"0 unchanged), 1 skipped\n"
@@ -1069,24 +1288,19 @@ func TestRunScanSkipsOperandThroughSymlinkIntoZFS(t *testing.T) {
 }
 
 // TestRunScanWalksOperandThroughSymlink scans data/daily, where data is
-// a symlink to a directory outside any .zfs directory. The operand is
-// scanned as usual, and its file is recorded by the path given.
+// a symlink to pool/data. The operand is scanned as usual, and its file
+// is recorded by its real path.
 func TestRunScanWalksOperandThroughSymlink(t *testing.T) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
-	dir := t.TempDir()
-	writeFile(t, dir, "pool/data/daily/f", pattern(1, 10))
+	dir := realTempDir(t)
+	f := writeFile(t, dir, "pool/data/daily/f", pattern(1, 10))
 
 	data := filepath.Join(dir, "data")
+	symlink(t, filepath.Join(dir, "pool", "data"), data)
 
-	err := os.Symlink(filepath.Join(dir, "pool", "data"), data)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	daily := filepath.Join(data, "daily")
-	stderr := scanOK(t, daily)
+	stderr := scanOK(t, filepath.Join(data, "daily"))
 
 	summary := "scan: 1 files seen (1 added, 0 updated, 0 removed, " +
 		"0 unchanged), 0 skipped\n"
@@ -1094,14 +1308,9 @@ func TestRunScanWalksOperandThroughSymlink(t *testing.T) {
 		t.Errorf("stderr = %q, want %q", stderr, summary)
 	}
 
-	db, err := openDB(path, reportParams)
-	if err != nil {
-		t.Fatal(err)
+	if got := storedPaths(t, path); !slices.Equal(got, []string{f}) {
+		t.Errorf("records = %q, want %q", got, []string{f})
 	}
-
-	t.Cleanup(func() { _ = db.Close() })
-
-	recordByPath(t, dbRecords(t, db), filepath.Join(daily, "f"))
 }
 
 func TestRunReportSucceeds(t *testing.T) {
@@ -1257,7 +1466,7 @@ func assertRunsUseDatabase(t *testing.T, dir, name string) {
 }
 
 func TestRunDatabasePathUsedAsGiven(t *testing.T) {
-	// README §Database: the path names the database file exactly. In
+	// README §Settings: the path names the database file exactly. In
 	// SQLite's connection string an unescaped ? or # would end the file
 	// name and % would start an escape, and a path starting with //
 	// could be read as a host name. %25 is a valid escape, so unescaped
@@ -1302,9 +1511,8 @@ func holdScanLock(t *testing.T, path string) {
 }
 
 func TestRunSecondScanFails(t *testing.T) {
-	// README §Database: while one scan holds the lock, a second scan
-	// fails at once, naming the lock file, without opening the
-	// database.
+	// README §Database: a second scan that finds the lock held fails
+	// at once, naming the lock file, without opening the database.
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
@@ -1363,7 +1571,7 @@ func assertSecondScanFails(t *testing.T, path string) {
 }
 
 func TestRunSecondScanThroughSymlinkFails(t *testing.T) {
-	// README §Database: every path to one database names the same lock
+	// README §Database: a path through a symlink names the same lock
 	// file, so while a scan holds it through one path, a scan through
 	// another fails, naming the lock file beside the database's real
 	// path.
@@ -1468,8 +1676,8 @@ func TestRunReportsDuringScan(t *testing.T) {
 }
 
 func TestRunStdoutClosedIsFatal(t *testing.T) {
-	// README §Error handling: a stdout write failure exits 1, reported
-	// in one line on stderr.
+	// README §Error handling: a failed write to stdout is a fatal error,
+	// exit 1, reported on stderr starting with "sfdupes:".
 	for _, name := range []string{cmdReport, cmdTrees, cmdInfo} {
 		t.Run(name, func(t *testing.T) {
 			t.Setenv(databaseEnv, testDBPath(t))

scan.go

@@ -209,29 +209,30 @@ func interrupted(walked int) error {
 	return errInterrupted
 }
 
-// resolveRoots converts each PATH operand to an absolute, lexically
-// cleaned path (symlinks are not resolved) and verifies that it
-// exists. Database records are keyed by absolute path, so scan results
-// must not depend on the working directory.
+// resolveRoots converts each PATH operand to its real path: absolute,
+// with every symlink in it followed. Database records are keyed by
+// that path, so scan results depend neither on the working directory
+// nor on the symlinks an operand was given through. An operand that
+// cannot be resolved, because it or a symlink's target does not exist
+// or cannot be read, is a fatal error before any scanning.
 func resolveRoots(roots []string) ([]string, error) {
-	abs := make([]string, 0, len(roots))
+	resolved := make([]string, 0, len(roots))
 
 	for _, root := range roots {
-		a, err := filepath.Abs(root)
+		a, err := absolutePath(root)
 		if err != nil {
 			return nil, fmt.Errorf("resolve %s: %w", root, err)
 		}
 
-		// A nonexistent operand is a fatal error before any scanning.
-		_, err = os.Lstat(a)
+		r, err := filepath.EvalSymlinks(a)
 		if err != nil {
-			return nil, err
+			return nil, fmt.Errorf("resolve %s: %w", root, err)
 		}
 
-		abs = append(abs, a)
+		resolved = append(resolved, r)
 	}
 
-	return abs, nil
+	return resolved, nil
 }
 
 // pruneRoots drops operands already covered by another operand:
@@ -417,14 +418,16 @@ 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. 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 are treated as if it had not been given:
-// those under no other root count as outside the roots and are not
-// deleted as unverified. An operand on a filesystem in rules that is not
-// persistent is dropped the same way, with a line saying so that is not
-// a warning, and is not counted as skipped. An operand that fails lstat
-// here is kept, and the walk warns about it unless it no longer exists.
+// directory named .zfs. The operands are real paths from resolveRoots,
+// 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
+// are treated as if it had not been given: those under no other root
+// count as outside the roots and are not deleted as unverified. An
+// operand on a filesystem in rules that is not persistent is dropped
+// the same way, with a line saying so that is not a warning, and is not
+// counted as skipped. An operand that fails lstat here is kept, and the
+// walk warns about it unless it no longer exists.
 func (s *scanState) walkableRoots(roots []string, rules walkRules) []string {
 	kept := make([]string, 0, len(roots))
 
@@ -554,7 +557,7 @@ func (s *scanState) walkPhase(events <-chan walkEvent, roots []string) {
 
 		// The space a file takes on disk can change while its size and
 		// mtime stay the same. ZFS, for one, counts a new file's blocks
-		// only seconds after the write.
+		// up to seconds after the write.
 		if old.diskSize != ev.rec.diskSize {
 			s.diskSizes = append(s.diskSizes, ev.rec)
 		}
@@ -894,19 +897,13 @@ 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, neither as given nor with its symlinks
-// resolved. Symlinks are never followed, including as operands.
+// inside a directory named .zfs. resolveRoots 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 {
 	// The walk never enters a .zfs directory, so it starts from nothing
-	// inside one either, not even through a symlink. An operand whose
-	// symlinks cannot be resolved is checked as given.
-	resolved, err := filepath.EvalSymlinks(root)
-	if err != nil {
-		resolved = root
-	}
-
-	if slices.Contains(strings.Split(filepath.Dir(root), "/"), ".zfs") ||
-		slices.Contains(strings.Split(filepath.Dir(resolved), "/"), ".zfs") {
+	// inside one either.
+	if slices.Contains(strings.Split(filepath.Dir(root), "/"), ".zfs") {
 		return fmt.Sprintf("walk %s: skipping operand inside a .zfs directory",
 			root)
 	}

scan_test.go

@@ -43,10 +43,16 @@ func writeFile(t *testing.T, dir, name string, data []byte) string {
 }
 
 // diskSizeOf returns the bytes the file at path takes on disk, from its
-// own lstat: st_blocks counts 512-byte units. ZFS counts a new file's
-// blocks only seconds after the write, and fsync does not hasten that.
-// A test therefore calls unix.Sync, which waits for it, before the scan
-// whose disk_size it compares with this.
+// own lstat: st_blocks counts 512-byte units. ZFS counts a write's
+// blocks only when it commits the write, up to seconds later, and one
+// commit can take the file through several growing sizes. So this value
+// can change at any moment. Neither fsync nor unix.Sync hastens that,
+// but a unix.Sync call often takes long enough that the blocks are
+// counted when it returns. A test that needs the value to change waits
+// for the change. A test that compares it with a scan's disk_size reads
+// it before and after the scan. The rewrite test rescans until the two
+// reads match, then compares exactly. The other two tests fail only on
+// a disk_size outside the two reads.
 func diskSizeOf(t *testing.T, path string) int64 {
 	t.Helper()
 
@@ -1082,12 +1088,13 @@ func TestScanOneFilesystemWalksNestedFileOperand(t *testing.T) {
 	}
 }
 
-// buildSmokeTree recreates the README smoke-test filesystem layout
-// with deterministic content and returns the tree root.
+// buildSmokeTree recreates the tree of the test under README
+// "Definition of done" with deterministic content and returns the tree
+// root.
 func buildSmokeTree(t *testing.T) string {
 	t.Helper()
 
-	dir := t.TempDir()
+	dir := realTempDir(t)
 	one := pattern(10, 2000)
 	f1 := pattern(30, 3000)
 	f2 := pattern(40, 100)
@@ -1447,20 +1454,26 @@ func TestScanStoresDiskSize(t *testing.T) {
 
 	unix.Sync() // see diskSizeOf
 
-	want := diskSizeOf(t, p)
-	if want == 0 || want >= length {
+	size := diskSizeOf(t, p)
+	if size == 0 || size >= length {
 		t.Fatalf("the file takes %d bytes on disk, want more than none "+
-			"and fewer than its length %d", want, length)
+			"and fewer than its length %d", size, length)
 	}
 
 	for _, operand := range []string{filepath.Dir(p), p} {
 		db := openTestDB(t)
+
+		// ZFS may count the blocks during the scan; see diskSizeOf.
+		before := diskSizeOf(t, p)
+
 		syncTree(t, db, operand)
 
+		after := diskSizeOf(t, p)
+
 		got := recordByPath(t, dbRecords(t, db), p).diskSize
-		if got != want {
-			t.Errorf("scan of %s: disk_size = %d, want %d",
-				operand, got, want)
+		if got < before || got > after {
+			t.Errorf("scan of %s: disk_size = %d, want %d to %d",
+				operand, got, before, after)
 		}
 	}
 }
@@ -1478,7 +1491,7 @@ func TestSyncScanRewriteUpdatesDiskSize(t *testing.T) {
 
 	syncTree(t, db, dir)
 
-	before := recordByPath(t, dbRecords(t, db), p).diskSize
+	recorded := recordByPath(t, dbRecords(t, db), p).diskSize
 
 	pokeAt(t, p, 512*1024, pattern(7, 64*1024))
 
@@ -1491,22 +1504,53 @@ func TestSyncScanRewriteUpdatesDiskSize(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	unix.Sync() // see diskSizeOf
-
-	want := diskSizeOf(t, p)
-	if want == before {
-		t.Fatalf("the file still takes %d bytes on disk after the write "+
-			"into its hole", want)
+	// Wait for ZFS to count the write; see diskSizeOf.
+	deadline := time.Now().Add(30 * time.Second)
+	for diskSizeOf(t, p) == recorded {
+		if time.Now().After(deadline) {
+			t.Fatalf("the file still takes %d bytes on disk 30 seconds "+
+				"after the write into its hole", recorded)
 		}
 
+		unix.Sync()
+	}
+
+	// ZFS may still be counting, so the size may change during a rescan.
+	// Only a rescan with the same size on both sides of it can be compared
+	// exactly. A rescan that keeps the old size still fails, because the
+	// wait made before differ from it.
+	for {
+		before := diskSizeOf(t, p)
+
 		st := syncTree(t, db, dir)
+
+		after := diskSizeOf(t, p)
+
 		if st != (scanStats{walked: 1, updated: 1}) {
 			t.Fatalf("rescan stats = %+v, want 1 updated", st)
 		}
 
+		if before == after {
 			got := recordByPath(t, dbRecords(t, db), p).diskSize
-	if got != want {
-		t.Errorf("disk_size = %d, want %d", got, want)
+			if got != after {
+				t.Errorf("disk_size = %d, want %d", got, after)
+			}
+
+			return
+		}
+
+		if time.Now().After(deadline) {
+			t.Fatalf("the size on disk was still changing 30 seconds after "+
+				"the write into its hole: %d, then %d", before, after)
+		}
+
+		// A later mtime makes the next rescan read the file again.
+		later = later.Add(time.Second)
+
+		err = os.Chtimes(p, later, later)
+		if err != nil {
+			t.Fatal(err)
+		}
 	}
 }
 
@@ -1532,15 +1576,21 @@ func TestSyncScanUnchangedUpdatesDiskSize(t *testing.T) {
 
 	unix.Sync() // see diskSizeOf
 
+	// ZFS may count the blocks during the rescan; see diskSizeOf.
+	before := diskSizeOf(t, p)
+
 	// A file read again would count as updated.
 	st := syncTree(t, db, dir)
+
+	after := diskSizeOf(t, p)
+
 	if st != (scanStats{walked: 1, unchanged: 1}) {
 		t.Fatalf("rescan stats = %+v, want 1 unchanged", st)
 	}
 
 	got := recordByPath(t, dbRecords(t, db), p).diskSize
-	if want := diskSizeOf(t, p); got != want {
-		t.Errorf("disk_size = %d, want %d", got, want)
+	if got < before || got > after {
+		t.Errorf("disk_size = %d, want %d to %d", got, before, after)
 	}
 }
 
@@ -2260,33 +2310,24 @@ func TestUnderRoot(t *testing.T) {
 }
 
 // TestRunScanPassesOverDatabase scans a tree that holds the scan's own
-// database, reached directly and through a symlinked directory. The
-// walk passes over the database file, its -wal and -shm files and its
-// .lock file with no line and no count, and the record an earlier scan
-// left for the .lock file is deleted. A rescan of the unchanged tree
-// updates nothing, and report lists none of the database's files.
+// database, and in one case also a hard link to the database file. The
+// walk knows the database's files by device ID and inode number, so it
+// passes over the database file, its -wal and -shm files, its .lock
+// file and the hard link with no line and no count. The record an
+// earlier scan left for the .lock file is deleted. A rescan of the
+// unchanged tree updates nothing, and report lists none of the
+// database's files.
 func TestRunScanPassesOverDatabase(t *testing.T) {
-	for _, viaSymlink := range []bool{false, true} {
-		t.Run(fmt.Sprintf("via symlink %v", viaSymlink), func(t *testing.T) {
-			base := t.TempDir()
-			tree := filepath.Join(base, "real", "tree")
-			operand := tree
+	for _, viaHardLink := range []bool{false, true} {
+		t.Run(fmt.Sprintf("via hard link %v", viaHardLink), func(t *testing.T) {
+			tree := realTempDir(t)
+			hardLink := filepath.Join(tree, "hardlink")
 
 			writeFile(t, tree, "a", pattern(1, 100))
 			writeFile(t, tree, "b", pattern(1, 100))
 			writeFile(t, tree, "empty1", nil)
 			writeFile(t, tree, "empty2", nil)
 
-			if viaSymlink {
-				err := os.Symlink(filepath.Join(base, "real"),
-					filepath.Join(base, "link"))
-				if err != nil {
-					t.Fatal(err)
-				}
-
-				operand = filepath.Join(base, "link", "tree")
-			}
-
 			dbPath := filepath.Join(tree, "db.sqlite")
 			t.Setenv(databaseEnv, dbPath)
 
@@ -2296,7 +2337,7 @@ func TestRunScanPassesOverDatabase(t *testing.T) {
 			}
 
 			err = applyChanges(t.Context(), db, []scanRec{
-				{path: filepath.Join(operand, "db.sqlite.lock")},
+				{path: filepath.Join(tree, "db.sqlite.lock")},
 			}, nil, nil)
 			if err != nil {
 				t.Fatal(err)
@@ -2304,16 +2345,29 @@ func TestRunScanPassesOverDatabase(t *testing.T) {
 
 			closeScanDatabase(t.Context(), db, dbPath)
 
-			assertScanSummary(t,
+			if viaHardLink {
+				err = os.Link(dbPath, hardLink)
+				if err != nil {
+					t.Fatal(err)
+				}
+			}
+
+			stderr := assertScanSummary(t,
 				"4 files seen (4 added, 0 updated, 1 removed, 0 unchanged)",
-				operand)
-			assertScanSummary(t,
+				tree)
+			stderr += assertScanSummary(t,
 				"4 files seen (0 added, 0 updated, 0 removed, 4 unchanged)",
-				operand)
+				tree)
+
+			if strings.Contains(stderr, hardLink) {
+				t.Errorf("scan stderr = %q, want no line naming %s",
+					stderr, hardLink)
+			}
 
 			report := runStdout(t, cmdReport)
 			if strings.Contains(report, "db.sqlite") ||
-				!strings.Contains(report, filepath.Join(operand, "empty2")) {
+				strings.Contains(report, hardLink) ||
+				!strings.Contains(report, filepath.Join(tree, "empty2")) {
 				t.Errorf("report = %q, want the empty files and none of "+
 					"the database's files", report)
 			}
@@ -2338,8 +2392,9 @@ func TestRunScanPassesOverDatabaseOperands(t *testing.T) {
 
 // assertScanSummary scans operands and fails the test unless the
 // summary line gives counts with nothing skipped, and the line naming
-// the database is the only one that names one of its files.
-func assertScanSummary(t *testing.T, counts string, operands ...string) {
+// the database is the only one that names one of its files. It returns
+// everything the scan printed to stderr.
+func assertScanSummary(t *testing.T, counts string, operands ...string) string {
 	t.Helper()
 
 	stderr := scanOK(t, operands...)
@@ -2353,4 +2408,6 @@ func assertScanSummary(t *testing.T, counts string, operands ...string) {
 		t.Errorf("scan %q: stderr = %q, want only the line naming the "+
 			"database to name one of its files", operands, stderr)
 	}
+
+	return stderr
 }

trees_test.go

@@ -15,9 +15,9 @@ import (
 const treesOpenLine = "[1/4] open: opening the database, elapsed 0s, " +
 	"remain unknown"
 
-// smokeTreeRecs mirrors the README smoke-test tree layout: /d/t1 and
-// /d/t2 are identical, /d/t3 differs from them only by one filename.
-// Each file takes one 4 KiB block on disk.
+// smokeTreeRecs mirrors the tree of the test under README "Definition
+// of done": /d/t1 and /d/t2 are identical, /d/t3 differs from them only
+// by one filename. Each file takes one 4 KiB block on disk.
 func smokeTreeRecs() []scanRec {
 	f1Head, f1Tail, f1Content := testHash("f1h"), testHash("f1t"), testHash("f1c")
 	f2Head, f2Tail, f2Content := testHash("f2h"), testHash("f2t"), testHash("f2c")