Rewrite README.md sentence by sentence for a newcomer

Rewrites `README.md` from scratch for
#135. Every statement was checked
against the code on `next` and against what the built binary prints on
small trees under `/var/tmp`. The headings that the code comments cite
are kept.

Where the old text and the repository disagreed, the new text states
what the code does. #140 lists
every such point. Among them: `@latest` installs the newest tagged
release, ten million files in both "Rationale" and "Design", no Windows
excludes, a relative operand is joined to the working directory as `pwd`
prints it, and an operand reached through a symlinked directory below
another operand is dropped (#144).

Dropped from "Constraints": the permission to add `github.com/spf13/viper`
if configuration-file support is ever needed.

Model: fable-5-1

TODO.md

@@ -29,10 +29,17 @@
 
 # Completed Steps
 
-- an operand under another is walked on its own when a directory between them,
+- `README.md` rewritten from scratch, sentence by sentence, as a newcomer reads
-  the inner operand included, is named `.zfs` or is a symlink. The walk of the
+  it. It leads with what the program is and how to use it. A reference section
-  outer operand does not reach it then. `scan` now records the files below it
+  covers every setting and every subcommand. Development and testing come last.
-  and no longer deletes their records (2026-10-26,
+  Every statement was checked against the code on `next`. Five comments in
+  `main_test.go` cite "Settings", where their rules now live. One comment each
+  in `scan_test.go`, `trees_test.go` and `exclude_test.go` cites what the README
+  now says (2026-10-26, https://git.eeqj.de/sneak/sfdupes/issues/135)
+
+- an operand at or inside a directory named `.zfs` is never scanned, whether
+  given alone or under another operand. `scan` warns about it, counts it as
+  skipped and does not walk it (2026-10-26,
   https://git.eeqj.de/sneak/sfdupes/issues/142)
 
 - a file or directory removed while the scan runs is not an error, in the walk

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

@@ -393,7 +393,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
@@ -648,7 +648,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) {
@@ -686,8 +686,8 @@ func TestRunScanRejectsWorkersBelowOne(t *testing.T) {
 func TestRunHelp(t *testing.T) {
 	t.Parallel()
 
-	// README §Subcommands: help goes to stderr, exits 0, and leaves
+	// README §Settings: help goes to stderr, exits 0, and leaves stdout
-	// stdout empty.
+	// empty.
 	cases := [][]string{{"--help"}, {"-h"}, {cmdScan, "--help"}}
 
 	for _, args := range cases {
@@ -713,8 +713,8 @@ func TestRunHelp(t *testing.T) {
 func TestRunVersion(t *testing.T) {
 	t.Parallel()
 
-	// README §Subcommands: the version is one line on stdout, with
+	// README §Settings: the version is one line on stdout, with nothing
-	// nothing on stderr, and exits 0.
+	// on stderr, and exits 0.
 	info, _ := debug.ReadBuildInfo()
 
 	for _, arg := range []string{"--version", "-v"} {
@@ -773,8 +773,8 @@ func TestBuildVersion(t *testing.T) {
 func TestRunVersionWriteFailureIsFatal(t *testing.T) {
 	t.Parallel()
 
-	// README §Error handling: a stdout write failure exits 1, reported
+	// README §Error handling: a failed write to stdout is a fatal error,
-	// in one line on stderr.
+	// exit 1, reported on stderr starting with "sfdupes:".
 	var stderr bytes.Buffer
 
 	code := run([]string{"--version"}, failingWriter{}, &stderr)
@@ -928,24 +928,21 @@ func TestRunScanWalksOperandUnderSymlinkOperand(t *testing.T) {
 }
 
 func TestRunScanSkipsZFSOperand(t *testing.T) {
-	path := testDBPath(t)
-	t.Setenv(databaseEnv, path)
-
 	zfs := filepath.Join(t.TempDir(), ".zfs")
-	snapshot := filepath.Join(zfs, "snapshot", "hourly")
+	f := writeFile(t, zfs, "snapshot/hourly/f", pattern(1, 10))
-	f := writeFile(t, snapshot, "f", pattern(1, 10))
 
-	// An operand beneath a .zfs directory is walked, because it is not
+	// No scan records a file inside a .zfs directory, so the record
-	// itself named .zfs.
+	// beneath the operand is written straight into the database.
-	scanOK(t, snapshot)
+	path := seedDatabase(t, []scanRec{{size: 10, path: f}})
+	t.Setenv(databaseEnv, path)
 
 	assertOperandSkipped(t, path, zfs, ".zfs directory", f)
 }
 
 // assertOperandSkipped scans operand alone and checks that it is skipped
 // as kind: a warning naming it, one skip in the summary, exit 0, and the
-// record for kept, which an earlier scan stored beneath operand, still
+// record for kept, stored beneath operand before this scan, still in the
-// in the database at dbPath.
+// database at dbPath.
 func assertOperandSkipped(t *testing.T, dbPath, operand, kind,
 	kept string,
 ) {
@@ -974,6 +971,121 @@ func assertOperandSkipped(t *testing.T, dbPath, operand, kind,
 	recordByPath(t, dbRecords(t, db), kept)
 }
 
+// TestRunScanSkipsOperandInsideZFS scans a directory inside a .zfs
+// directory, first alone and then under another operand. Each time it
+// is warned about and counted as skipped, and nothing in it is walked.
+// The other operand is scanned as usual.
+func TestRunScanSkipsOperandInsideZFS(t *testing.T) {
+	path := testDBPath(t)
+	t.Setenv(databaseEnv, path)
+
+	dir := t.TempDir()
+	hourly := filepath.Join(dir, ".zfs", "snapshot", "hourly")
+	writeFile(t, hourly, "f", pattern(1, 10))
+	f := writeFile(t, dir, "f", pattern(2, 10))
+
+	warning := "walk " + hourly + ": skipping operand inside a .zfs directory\n"
+
+	for _, tc := range []struct {
+		operands []string
+		summary  string
+	}{
+		{
+			[]string{hourly},
+			"scan: 0 files seen (0 added, 0 updated, 0 removed, " +
+				"0 unchanged), 1 skipped\n",
+		},
+		{
+			[]string{dir, hourly},
+			"scan: 1 files seen (1 added, 0 updated, 0 removed, " +
+				"0 unchanged), 1 skipped\n",
+		},
+	} {
+		stderr := scanOK(t, tc.operands...)
+		if !strings.Contains(stderr, warning) ||
+			!strings.Contains(stderr, tc.summary) {
+			t.Errorf("scan %q: stderr = %q, want %q and %q", tc.operands,
+				stderr, warning, tc.summary)
+		}
+	}
+
+	db, err := openDB(path, reportParams)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	if got := recordPaths(dbRecords(t, db)); !slices.Equal(got, []string{f}) {
+		t.Errorf("records = %q, want %q", got, []string{f})
+	}
+}
+
+// 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.
+func TestRunScanSkipsOperandThroughSymlinkIntoZFS(t *testing.T) {
+	t.Setenv(databaseEnv, testDBPath(t))
+
+	dir := t.TempDir()
+	writeFile(t, dir, "pool/.zfs/snapshot/daily/f", pattern(1, 10))
+
+	snaps := filepath.Join(dir, "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)
+
+	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"
+
+	if !strings.Contains(stderr, warning) ||
+		!strings.Contains(stderr, summary) {
+		t.Errorf("stderr = %q, want %q and %q", stderr, warning, summary)
+	}
+}
+
+// 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.
+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))
+
+	data := filepath.Join(dir, "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)
+
+	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) {
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
@@ -1122,7 +1234,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
@@ -1167,9 +1279,8 @@ func holdScanLock(t *testing.T, path string) {
 }
 
 func TestRunSecondScanFails(t *testing.T) {
-	// README §Database: while one scan holds the lock, a second scan
+	// README §Database: a second scan that finds the lock held fails
-	// fails at once, naming the lock file, without opening the
+	// at once, naming the lock file, without opening the database.
-	// database.
 	path := testDBPath(t)
 	t.Setenv(databaseEnv, path)
 
@@ -1228,7 +1339,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.
@@ -1333,8 +1444,8 @@ func TestRunReportsDuringScan(t *testing.T) {
 }
 
 func TestRunStdoutClosedIsFatal(t *testing.T) {
-	// README §Error handling: a stdout write failure exits 1, reported
+	// README §Error handling: a failed write to stdout is a fatal error,
-	// in one line on stderr.
+	// 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

@@ -48,11 +48,6 @@ const sampleWindow = 1024 * 1024
 // and hash worker pools.
 const workQueueDepth = 1024
 
-// zfsDirName is the name of the directory in which ZFS shows a
-// filesystem's snapshots. The walk never enters one, since it would
-// list every file once per snapshot.
-const zfsDirName = ".zfs"
-
 // errInterrupted reports a scan stopped by SIGINT or SIGTERM. runScan
 // has already printed its line, so run prints nothing more.
 var errInterrupted = errors.New("scan interrupted")
@@ -277,10 +272,9 @@ func pruneRoots(roots []string, oneFS bool, rules walkRules,
 }
 
 // walkReaches reports whether the walk of operand above reaches r, an
-// operand under it. That walk never follows a symlink. It does not
+// operand under it. That walk does not enter a default exclude in
-// enter a directory named .zfs, nor a default exclude in rules, nor a
+// rules, nor a directory that device puts on a filesystem in rules that
-// directory that device puts on a filesystem in rules that is not
+// is not persistent, nor, with -x, one that device puts on a different
-// persistent, nor, with -x, one that device puts on a different
 // filesystem than above, when device knows above's. It reaches every
 // regular file in a directory it enters, so for a regular-file operand
 // the directories checked start at its directory; they end below above.
@@ -301,15 +295,6 @@ func walkReaches(above, r string, oneFS bool, rules walkRules,
 			return false
 		}
 
-		if filepath.Base(dir) == zfsDirName {
-			return false
-		}
-
-		fi, err = os.Lstat(dir)
-		if err == nil && fi.Mode()&fs.ModeSymlink != 0 {
-			return false
-		}
-
 		dev, ok := device(dir)
 		if !ok {
 			continue
@@ -398,7 +383,8 @@ func (s *scanState) runPhases(ctx context.Context, roots []string,
 ) error {
 	// Types and filesystems are checked before pruning so that an
 	// operand under a dropped one is still scanned, not dropped as lying
-	// under it.
+	// under it, and so that an operand inside a .zfs directory gets its
+	// warning even when it lies under another operand.
 	roots = pruneRoots(s.walkableRoots(roots, rules), oneFS, rules,
 		deviceOfPath)
 
@@ -426,15 +412,15 @@ 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. Every other operand is warned
+// files, and directories not named .zfs, none of them inside a
-// about, counted as skipped, and dropped. A dropped operand is no
+// directory named .zfs. Every other operand is warned about, counted as
-// longer a root, so the records stored beneath it are treated as if it
+// skipped, and dropped. A dropped operand is no longer a root, so the
-// had not been given: those under no other root count as outside the
+// records stored beneath it are treated as if it had not been given:
-// roots and are not deleted as unverified. An operand on a filesystem
+// those under no other root count as outside the roots and are not
-// in rules that is not persistent is dropped the same way, with a line
+// deleted as unverified. An operand on a filesystem in rules that is not
-// saying so that is not a warning, and is not counted as skipped. An
+// persistent is dropped the same way, with a line saying so that is not
-// operand that fails lstat here is kept, and the walk warns about it
+// a warning, and is not counted as skipped. An operand that fails lstat
-// unless it no longer exists.
+// 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))
 
@@ -889,16 +875,31 @@ 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. Symlinks are
+// does: a regular file, or a directory not named .zfs, that is not
-// never followed, including as operands.
+// inside a directory named .zfs, neither as given nor with its symlinks
+// resolved. Symlinks are never followed, including as operands.
 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") {
+		return fmt.Sprintf("walk %s: skipping operand inside a .zfs directory",
+			root)
+	}
+
 	var kind string
 
 	switch mode := fi.Mode(); {
 	case mode.IsRegular():
 		return ""
 	case mode.IsDir():
-		if filepath.Base(root) != zfsDirName {
+		if filepath.Base(root) != ".zfs" {
 			return ""
 		}
 
@@ -1168,7 +1169,7 @@ func subdirJob(ctx context.Context, p string, e fs.DirEntry,
 	parent dirJob, oneFS bool, rules walkRules,
 	events chan<- walkEvent,
 ) (dirJob, bool) {
-	if e.Name() == zfsDirName {
+	if e.Name() == ".zfs" {
 		return dirJob{}, false
 	}
 

scan_test.go

@@ -1064,8 +1064,9 @@ func TestScanOneFilesystemWalksNestedFileOperand(t *testing.T) {
 	}
 }
 
-// buildSmokeTree recreates the README smoke-test filesystem layout
+// buildSmokeTree recreates the tree of the test under README
-// with deterministic content and returns the tree root.
+// "Definition of done" with deterministic content and returns the tree
+// root.
 func buildSmokeTree(t *testing.T) string {
 	t.Helper()
 
@@ -1672,81 +1673,6 @@ func TestSyncScanOverlappingRoots(t *testing.T) {
 	}
 }
 
-// TestScanWalksOperandInZFSDirectory checks that an operand inside a
-// directory named .zfs below another operand is walked on its own,
-// since the walk of the other operand does not enter .zfs. The file
-// under it is recorded, and a second scan keeps the record.
-func TestScanWalksOperandInZFSDirectory(t *testing.T) {
-	t.Parallel()
-
-	dir := t.TempDir()
-	db := openTestDB(t)
-	f := writeFile(t, dir, "pool/.zfs/snapshot/daily/f", pattern(1, 10))
-	daily := filepath.Dir(f)
-
-	syncTree(t, db, dir, daily)
-	recordByPath(t, dbRecords(t, db), f)
-
-	syncTree(t, db, dir, daily)
-	recordByPath(t, dbRecords(t, db), f)
-}
-
-// TestScanWalksOperandBehindSymlink checks that an operand reached
-// through a symlinked directory below another operand is walked on its
-// own, since the walk of the other operand does not follow the symlink.
-// The file under it is recorded, and a second scan keeps the record.
-func TestScanWalksOperandBehindSymlink(t *testing.T) {
-	t.Parallel()
-
-	dir := t.TempDir()
-	target := t.TempDir()
-	db := openTestDB(t)
-	writeFile(t, target, "sub/f", pattern(1, 10))
-
-	link := filepath.Join(dir, "link")
-
-	err := os.Symlink(target, link)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	sub := filepath.Join(link, "sub")
-	f := filepath.Join(sub, "f")
-
-	syncTree(t, db, dir, sub)
-	recordByPath(t, dbRecords(t, db), f)
-
-	syncTree(t, db, dir, sub)
-	recordByPath(t, dbRecords(t, db), f)
-}
-
-// TestScanDropsOperandReachedBehindSymlink checks that an operand under
-// another one is still dropped when both lie behind the same symlinked
-// directory: the walk of the other operand starts past the symlink and
-// reaches it, so the file under it is walked once.
-func TestScanDropsOperandReachedBehindSymlink(t *testing.T) {
-	t.Parallel()
-
-	dir := t.TempDir()
-	target := t.TempDir()
-	db := openTestDB(t)
-	writeFile(t, target, "sub/deeper/f", pattern(1, 10))
-
-	link := filepath.Join(dir, "link")
-
-	err := os.Symlink(target, link)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	sub := filepath.Join(link, "sub")
-
-	st := syncTree(t, db, sub, filepath.Join(sub, "deeper"))
-	if st != (scanStats{walked: 1, added: 1}) {
-		t.Fatalf("stats = %+v, want 1 walked and added", st)
-	}
-}
-
 // TestScanHashesUniqueSize checks that a file whose size no other file
 // shares is hashed like every other file.
 func TestScanHashesUniqueSize(t *testing.T) {
@@ -2160,16 +2086,6 @@ func TestPruneRoots(t *testing.T) {
 		t.Fatalf("pruneRoots with %s not persistent = %q, want %q",
 			pqRoot, got, want)
 	}
-
-	// Nor does it enter a directory named .zfs, so /p/.zfs/s is kept. The
-	// walk of /p/.zfs/s reaches /p/.zfs/s/t, which is dropped.
-	got = pruneRoots([]string{"/p", "/p/.zfs/s", "/p/.zfs/s/t"}, false,
-		walkRules{}, device)
-
-	want = []string{"/p", "/p/.zfs/s"}
-	if !slices.Equal(got, want) {
-		t.Fatalf("pruneRoots with .zfs = %q, want %q", got, want)
-	}
 }
 
 func TestReportsNeverTouchFilesystem(t *testing.T) {

trees_test.go

@@ -15,8 +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
+// smokeTreeRecs mirrors the tree of the test under README "Definition
-// /d/t2 are identical, /d/t3 differs from them only by one filename.
+// of done": /d/t1 and /d/t2 are identical, /d/t3 differs from them only
+// by one filename.
 func smokeTreeRecs() []scanRec {
 	f1Head, f1Tail, f1Content := testHash("f1h"), testHash("f1t"), testHash("f1c")
 	f2Head, f2Tail, f2Content := testHash("f2h"), testHash("f2t"), testHash("f2c")