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()