Resolve scan operands to their real paths (closes #144)

scan now resolves every operand with its symlinks followed before the
walk, and uses that real path for pruning, walking, records and
warnings. A relative operand is joined to the working directory as the
kernel reports it, so a ".." after a symlink counts from its target, as
with realpath. A symlink operand is scanned at its target instead of
skipped. An operand given through a symlink below another operand, to a
directory outside it, is walked on its own instead of dropped with its
records deleted. An operand that cannot be resolved is a fatal error
naming the operand as given. The walk itself still follows no symlink.

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

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: {

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
@@ -649,7 +651,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 +689,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 +716,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 +776,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)
@@ -895,54 +897,262 @@ 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)
+	}
+}
+
+// assertSummary checks that stderr holds the scan summary line want.
+func assertSummary(t *testing.T, stderr, want string) {
+	t.Helper()
+
+	if !strings.Contains(stderr, want) {
+		t.Errorf("stderr = %q, want %q", stderr, want)
+	}
+}
+
+// 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)
+
+	assertSummary(t, scanOK(t, link), "scan: 1 files seen (1 added, "+
+		"0 updated, 0 removed, 0 unchanged), 0 skipped\n")
+
+	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)
+	assertSummary(t, scanOK(t, link, filepath.Join(link, "sub")),
+		"scan: 1 files seen (1 added, 0 updated, 0 removed, "+
+			"0 unchanged), 0 skipped\n")
+
+	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"))
+	assertSummary(t, stderr, "scan: 2 files seen (1 added, 0 updated, "+
+		"0 removed, 1 unchanged), 0 skipped\n")
+
+	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)
+
+	assertSummary(t, scanOK(t, dir, link), "scan: 1 files seen (1 added, "+
+		"0 updated, 0 removed, 0 unchanged), 0 skipped\n")
+
+	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)
+	}
+
+	assertSummary(t, stderr, "scan: 0 files seen (0 added, 0 updated, "+
+		"0 removed, 0 unchanged), 1 skipped\n")
 }
 
 func TestRunScanSkipsZFSOperand(t *testing.T) {
@@ -1041,23 +1251,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,39 +1275,25 @@ 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)
+	assertSummary(t, scanOK(t, filepath.Join(data, "daily")),
+		"scan: 1 files seen (1 added, 0 updated, 0 removed, "+
+			"0 unchanged), 0 skipped\n")
+
+	if got := storedPaths(t, path); !slices.Equal(got, []string{f}) {
+		t.Errorf("records = %q, want %q", got, []string{f})
 	}
-
-	daily := filepath.Join(data, "daily")
-	stderr := scanOK(t, daily)
-
-	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)
-	}
-
-	db, err := openDB(path, reportParams)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	t.Cleanup(func() { _ = db.Close() })
-
-	recordByPath(t, dbRecords(t, db), filepath.Join(daily, "f"))
 }
 
 func TestRunReportSucceeds(t *testing.T) {
@@ -1257,7 +1449,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 +1494,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 +1554,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 +1659,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,8 +1088,9 @@ 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()
 
@@ -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
+	// 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)
+		}
 
-	want := diskSizeOf(t, p)
-	if want == before {
-		t.Fatalf("the file still takes %d bytes on disk after the write "+
-			"into its hole", want)
+		unix.Sync()
 	}
 
-	st := syncTree(t, db, dir)
-	if st != (scanStats{walked: 1, updated: 1}) {
-		t.Fatalf("rescan stats = %+v, want 1 updated", st)
-	}
+	// 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)
 
-	got := recordByPath(t, dbRecords(t, db), p).diskSize
-	if got != want {
-		t.Errorf("disk_size = %d, want %d", got, want)
+		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 != 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")