scan: drop the stray [flags] from the usage line (closes #169)

The scan Use string already names every flag, so cobra no longer appends
its generic [flags]. A test checks the usage line in the help and in the
usage error against the one README.md shows.

Model: opus-5-5

README.md

@@ -208,8 +208,8 @@ makes the comparison exact. Reading samples cuts a 150 GiB file to about 150 MiB
 of reads, at the price of a comparison that is not exact.
 
 The hashes live in a database that is kept between runs. A rescan reads only new
-files, and files whose size or modification time (mtime) differs from their
+files, and files whose size changed or whose modification time (mtime) is newer
-record. All analysis then works from the database alone.
+than recorded. All analysis then works from the database alone.
 
 The goal is whole duplicated trees, not only single files. A download extracted
 twice, or a project copied once too often, is such a tree. It can be removed as
@@ -410,16 +410,17 @@ operands:
 
 - A file not yet in the database is hashed and inserted.
 - A file already in the database is not read again when its size and mtime match
-  its record. This is what makes a daily rescan cheap.
+  its record. The mtime matches when it is not newer than the recorded one. This
+  is what makes a daily rescan cheap.
 - When such a file's size on disk differs from its recorded `disk_size`, `scan`
   updates `disk_size` alone. It still does not read the file, and counts it as
   unchanged. ZFS, for example, counts a new file's blocks up to seconds after
   the write. A block is the unit in which a filesystem allocates disk space. A
   file scanned within those seconds gets its real `disk_size` at the next scan.
-- `scan` hashes a file again when its size or its mtime differs from its record.
+- `scan` hashes a file again when its size differs or its mtime is newer. The
-  An older mtime counts as much as a newer one. A file put back by `cp -p`,
+  mtime is compared to the nanosecond, as finely as the filesystem records it. A
-  `rsync -a` or a restore from backup often has an older mtime. The mtime is
+  same-size rewrite counts as a change whenever the filesystem gives it a later
-  compared to the nanosecond, as finely as the filesystem records it.
+  mtime, even within the same second.
 - The scan deletes each record under a scanned operand whose file it could not
   verify. That covers deleted files, and paths the scan could not stat or read
   this run. To stat a file is to read its details, such as its size, without

TODO.md

@@ -29,6 +29,9 @@
 Newest first. An entry ends with its date and its issue or branch, where those
 are known.
 
+- The usage line of `scan` no longer ends in `[flags]`. It is the line
+  `README.md` shows under "Subcommands" (2026-11-11,
+  https://git.eeqj.de/sneak/sfdupes/issues/169)
 - `report` and `trees` leave out empty files. `report` writes no group of size
   0, and `trees` writes no group whose trees hold 0 bytes. An empty file still
   counts toward a tree's digest (2026-11-11,

internal/sfdupes/cli.go

@@ -215,10 +215,13 @@ func newScanCommand() *cobra.Command {
 	short := "Walk trees and synchronize the scan database"
 
 	scanCmd := &cobra.Command{
-		Use:   cmdScan + " [--workers N] [-x] [--no-default-excludes] PATH...",
+		Use: cmdScan + " [--workers N] [-x] [--no-default-excludes] PATH...",
-		Short: short,
+		// The Use line already names every flag, so cobra must not
-		Long:  short + ".\n\n" + defaultExcludesHelp(runtime.GOOS),
+		// append its generic "[flags]" to it.
-		Args:  cobra.MinimumNArgs(1),
+		DisableFlagsInUseLine: true,
+		Short:                 short,
+		Long:                  short + ".\n\n" + defaultExcludesHelp(runtime.GOOS),
+		Args:                  cobra.MinimumNArgs(1),
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			return checkScanWorkers(cmd, scanWorkers)
 		},

internal/sfdupes/cli_test.go

@@ -714,6 +714,34 @@ func TestRunHelp(t *testing.T) {
 	}
 }
 
+func TestRunScanUsageLine(t *testing.T) {
+	t.Parallel()
+
+	// README §Subcommands shows this usage line for scan, and the help
+	// and the usage error both print it.
+	const want = "\n  sfdupes scan [--workers N] [-x] [--no-default-excludes] PATH...\n"
+
+	cases := map[string][]string{
+		"help":          {cmdScan, "-h"},
+		"missing paths": {cmdScan},
+	}
+
+	for name, args := range cases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var stdout, stderr bytes.Buffer
+
+			run(args, &stdout, &stderr)
+
+			if !strings.Contains(stderr.String(), want) {
+				t.Errorf("run(%v) stderr = %q, want the usage line %q",
+					args, stderr.String(), want)
+			}
+		})
+	}
+}
+
 func TestRunVersion(t *testing.T) {
 	t.Parallel()
 

internal/sfdupes/scan.go

@@ -545,7 +545,7 @@ func (s *scanState) walkPhase(events <-chan walkEvent, roots []string) {
 		prog.increment()
 
 		old, ok := s.existing[ev.rec.path]
-		if !ok || old.size != ev.rec.size || !ev.rec.mtime.Equal(old.mtime) {
+		if !ok || old.size != ev.rec.size || mtimeAfter(ev.rec.mtime, old.mtime) {
 			s.toHash = append(s.toHash, ev.rec)
 
 			continue
@@ -780,6 +780,16 @@ func (s *scanState) updatePhase(ctx context.Context) error {
 	return applyChanges(ctx, s.db, nil, deletes, prog)
 }
 
+// mtimeAfter reports whether mtime a is later than mtime b.
+// Not a.After(b): time.Time wraps an mtime past year 292 billion; Unix() undoes it.
+func mtimeAfter(a, b time.Time) bool {
+	if a.Unix() != b.Unix() {
+		return a.Unix() > b.Unix()
+	}
+
+	return a.Nanosecond() > b.Nanosecond()
+}
+
 // underAnyRoot reports whether path is any of the roots or lies under
 // one of them.
 func underAnyRoot(path string, roots []string) bool {

internal/sfdupes/scan_test.go

@@ -1384,47 +1384,6 @@ func TestSyncScanMtimeBump(t *testing.T) {
 	}
 }
 
-// TestSyncScanMtimeMovedBack replaces a file with other content of the
-// same size and an older mtime, as cp -p or a restore from backup does.
-// The next scan must hash the file again.
-func TestSyncScanMtimeMovedBack(t *testing.T) {
-	t.Parallel()
-
-	dir := t.TempDir()
-	db := openTestDB(t)
-	a := writeFile(t, dir, "a.bin", pattern(1, 500))
-
-	recorded := time.Date(2026, 1, 2, 3, 4, 5, 0, time.UTC)
-
-	err := os.Chtimes(a, recorded, recorded)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	syncTree(t, db, dir)
-
-	replaced := pattern(3, 500)
-	writeFile(t, dir, "a.bin", replaced)
-
-	older := recorded.Add(-time.Hour)
-
-	err = os.Chtimes(a, older, older)
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	st := syncTree(t, db, dir)
-	if st != (scanStats{walked: 1, updated: 1}) {
-		t.Fatalf("rescan stats = %+v, want 1 updated", st)
-	}
-
-	assertWholeFileHashed(t, db, a, replaced)
-
-	if r := recordByPath(t, dbRecords(t, db), a); !r.mtime.Equal(older) {
-		t.Fatalf("mtime = %v, want %v", r.mtime, older)
-	}
-}
-
 // assertWholeFileHashed fails unless the record for path holds the
 // whole-file hash of data as its head, tail, and content.
 func assertWholeFileHashed(t *testing.T, db *sql.DB, path string,