Refuse an unversioned database that already has a files table (closes #11)

An unversioned database (user_version 0) that already contains a files
table was not created by this build; it is a foreign or partially
initialized file. Adopting it silently could corrupt unrelated data, so
createSchema now checks for a files table first and, when one exists,
returns the schema-version error telling the operator to remove the file
and rescan. A genuinely empty database is still created and stamped as
before.

Model: opus-4-8 (implementation); opus-5-5 (rebase)

.dockerignore

@@ -1,4 +1,9 @@
-.git
+# .git is sent without its config. Without a VERSION build argument the
+# stage that compiles runs `git describe --tags --always` on .git, which
+# does not need .git/config; that file can hold a credential, such as a
+# password in a remote URL or the token the CI checkout step stores there.
+.git/config
+
 .claude
 .DS_Store
 sfdupes

.gitea/workflows/check.yml

@@ -6,4 +6,6 @@ jobs:
         steps:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+              with:
+                  fetch-depth: 0
             - run: script/cibuild

Dockerfile

@@ -108,7 +108,19 @@ ARG CHECK_EPOCH
 RUN echo "gate test, epoch ${CHECK_EPOCH}" && make test
 RUN echo "gate fmt-check, epoch ${CHECK_EPOCH}" && make fmt-check
 
-RUN make build
+# The version stamped into the binary: the VERSION build argument when
+# one is given, otherwise `git describe --tags --always` of the .git in
+# the build context (git is installed by script/bootstrap above). A
+# context that carries .git and still yields no version fails the build;
+# with neither, as from a source tarball, it is "dev".
+ARG VERSION
+RUN version="${VERSION:-$(git describe --tags --always || echo dev)}"; \
+    if [ -e .git ] && { [ -z "$version" ] || [ "$version" = dev ] || \
+        [ "$version" = unknown ]; }; then \
+        echo "no version could be derived although the build context carries .git" >&2; \
+        exit 1; \
+    fi; \
+    make build VERSION="$version"
 
 # Runtime stage
 # alpine:3.22, 2026-07-23

README.md

@@ -428,6 +428,15 @@ first	dupe	size
 /srv/a/big.iso	/srv/c/big-copy2.iso	4294967296
 ```
 
+Paths are raw bytes and may hold any byte except NUL, so the path
+columns (`first` and `dupe`) are escaped to keep every row one line of
+tab-separated fields: a backslash is written as `\\`, a tab as `\t`, a
+newline as `\n`, and a carriage return as `\r`. Every other byte is
+written unchanged, including bytes that are not valid UTF-8. Undoing
+those four escapes gives back the stored path. Grouping and ordering
+use the stored path, not the escaped one. The warnings `scan` prints on
+stderr are escaped the same way, so each warning is one line.
+
 Summary to stderr: records read, number of duplicate groups, number of
 dupe files, and total reclaimable bytes (sum of `size` over all dupe
 rows) in human units.
@@ -499,6 +508,9 @@ first	dupe	files	size
 /srv/a/project	/srv/backup/project	3417	104857600
 ```
 
+The `first` and `dupe` paths are escaped as described under "Report
+output format". The root directory's path is `/`.
+
 Summary to stderr: records read, number of duplicate-tree groups,
 number of dupe trees, and total reclaimable bytes (sum of `size` over
 all dupe rows) in human units.

TODO.md

@@ -29,6 +29,25 @@
 
 # Completed Steps
 
+- refuse an unversioned database that already has a `files` table with
+  a clear schema-version error (2026-10-03,
+  https://git.eeqj.de/sneak/sfdupes/issues/11)
+
+- escape tabs, newlines, carriage returns and backslashes in report,
+  trees and warning paths; the root directory's path is `/`
+  (2026-10-03, https://git.eeqj.de/sneak/sfdupes/issues/7)
+
+- stamp the git tag or short commit in a plain `docker build .`
+  instead of `dev` (2026-10-02, branch `next`, closes
+  https://git.eeqj.de/sneak/sfdupes/issues/67): `.dockerignore` now
+  sends `.git`, without `.git/config`, and the `Dockerfile` build
+  stage takes the `VERSION` build argument when one is given,
+  otherwise `git describe --tags --always` of that `.git`. The build
+  fails if the context carries `.git` and the version still comes out
+  empty, `dev` or `unknown`. The CI checkout step fetches the full
+  history (`fetch-depth: 0`) so CI sees the tag and stamps the same
+  value as `make build`.
+
 - replace the 1 KiB end-window sampling with the head/tail plus
   content-hash ladder (2026-09-22, branch `next`, closes
   https://git.eeqj.de/sneak/sfdupes/issues/61): a file under 10 MiB is

db.go

@@ -176,9 +176,30 @@ func initSchema(ctx context.Context, db *sql.DB) error {
 }
 
 // createSchema applies the schema to a fresh database and stamps the
-// schema version.
+// schema version. A database with user_version 0 that already has a
+// files table was not created by this build — a foreign or partially
+// initialized file. Adopting it silently could corrupt unrelated data,
+// so that is a fatal schema-version error telling the operator to
+// remove the file and rescan.
 func createSchema(ctx context.Context, db *sql.DB) error {
-	_, err := db.ExecContext(ctx, createTableSQL)
+	var name string
+
+	err := db.QueryRowContext(ctx,
+		"SELECT name FROM sqlite_master "+
+			"WHERE type = 'table' AND name = 'files'").Scan(&name)
+
+	switch {
+	case err == nil:
+		return fmt.Errorf(
+			"has a files table but no schema version; "+
+				"remove the file and rescan: %w", errSchemaVersion)
+	case errors.Is(err, sql.ErrNoRows):
+		// Genuinely empty: create the schema below.
+	default:
+		return fmt.Errorf("check for files table: %w", err)
+	}
+
+	_, err = db.ExecContext(ctx, createTableSQL)
 	if err != nil {
 		return fmt.Errorf("create schema: %w", err)
 	}

db_test.go

@@ -78,6 +78,38 @@ func TestOpenScanDatabaseCreates(t *testing.T) {
 	}
 }
 
+func TestOpenScanDatabaseUnversionedForeign(t *testing.T) {
+	t.Parallel()
+
+	path := testDBPath(t)
+
+	// A database that has a files table but user_version 0 — a foreign
+	// or partially initialized file. scan must refuse it with a clear
+	// schema-version error, not adopt it and not emit a raw SQLite
+	// "table files already exists".
+	db, err := openDB(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.ExecContext(t.Context(), "CREATE TABLE files (x INTEGER)")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_ = db.Close()
+
+	_, err = openScanDatabase(t.Context(), path)
+	if !errors.Is(err, errSchemaVersion) {
+		t.Fatalf("err = %v, want errSchemaVersion", err)
+	}
+
+	if !strings.Contains(err.Error(), "remove the file and rescan") {
+		t.Fatalf("err = %v, want it to tell the operator to remove and rescan",
+			err)
+	}
+}
+
 func TestOpenReportDatabaseMissing(t *testing.T) {
 	t.Parallel()
 

progress.go

@@ -106,6 +106,8 @@ func (p *progress) increment() {
 }
 
 // warnf prints a one-line warning to stderr without corrupting the bar.
+// The whole message is escaped like a report's path columns, so a path
+// holding a newline cannot split the warning.
 func (p *progress) warnf(format string, args ...any) {
 	if p == nil {
 		return
@@ -115,7 +117,7 @@ func (p *progress) warnf(format string, args ...any) {
 		_ = p.bar.Clear()
 	}
 
-	fmt.Fprintf(os.Stderr, format+"\n", args...)
+	fmt.Fprintln(os.Stderr, escapePath(fmt.Sprintf(format, args...)))
 }
 
 // finish terminates the pass's display.

report.go

@@ -87,7 +87,7 @@ func runReport(ctx context.Context) error {
 	for _, g := range dupes {
 		for _, p := range g.paths[1:] {
 			_, err = fmt.Fprintf(out, "%s\t%s\t%d\n",
-				g.paths[0], p, g.size)
+				escapePath(g.paths[0]), escapePath(p), g.size)
 			if err != nil {
 				return fmt.Errorf("write stdout: %w", err)
 			}
@@ -156,6 +156,21 @@ func collectDupeGroups(recs []scanRec) []dupeGroup {
 	return dupes
 }
 
+// escapePath returns a path as it is written in a report column (README
+// "Report output format"): a backslash, tab, newline or carriage return
+// becomes \\, \t, \n or \r, and every other byte is kept as it is.
+// Grouping and sorting use the raw path, never this form.
+func escapePath(p string) string {
+	// Most paths need no escaping; skip building a replacer for them.
+	if !strings.ContainsAny(p, "\\\t\n\r") {
+		return p
+	}
+
+	return strings.NewReplacer(
+		`\`, `\\`, "\t", `\t`, "\n", `\n`, "\r", `\r`,
+	).Replace(p)
+}
+
 // humanBytes formats a byte count in human units (binary prefixes).
 func humanBytes(n int64) string {
 	const unit = 1024

report_test.go

@@ -1,10 +1,128 @@
 package main
 
 import (
+	"bytes"
+	"io"
+	"os"
+	"path/filepath"
 	"slices"
 	"testing"
 )
 
+// awkwardDir is a directory name holding every byte the reports escape.
+const awkwardDir = "/d/\tone\ntwo\rthree\\four"
+
+// awkwardPairRecs is a duplicate pair in sibling directories /d/A and
+// awkwardDir. A raw tab sorts before "A" but its escaped form `\t`
+// sorts after it, so awkwardDir coming first shows that sorting uses
+// the raw path.
+func awkwardPairRecs() []scanRec {
+	return []scanRec{
+		{size: 5, head: "h", tail: "t", content: "c", path: "/d/A/f"},
+		{size: 5, head: "h", tail: "t", content: "c", path: awkwardDir + "/f"},
+	}
+}
+
+// seedDatabase writes recs into a fresh database and returns its path.
+func seedDatabase(t *testing.T, recs []scanRec) string {
+	t.Helper()
+
+	path := testDBPath(t)
+
+	db, err := openScanDatabase(t.Context(), path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = applyChanges(t.Context(), db, recs, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = db.Close()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return path
+}
+
+func TestRunReportEscapesPaths(t *testing.T) {
+	t.Setenv(databaseEnv, seedDatabase(t, awkwardPairRecs()))
+
+	var stderr bytes.Buffer
+
+	stdout := captureStdout(t)
+
+	code := run([]string{cmdReport}, &stderr)
+	if code != exitOK {
+		t.Fatalf("run(report) = %d, want %d; stderr: %s",
+			code, exitOK, stderr.String())
+	}
+
+	want := "first\tdupe\tsize\n" +
+		`/d/\tone\ntwo\rthree\\four/f` + "\t/d/A/f\t5\n"
+	if got := stdout(); got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+}
+
+func TestEscapePath(t *testing.T) {
+	t.Parallel()
+
+	cases := map[string]string{
+		"/srv/plain":    "/srv/plain",
+		"/a\tb":         `/a\tb`,
+		"/a\nb":         `/a\nb`,
+		"/a\rb":         `/a\rb`,
+		`/a\b`:          `/a\\b`,
+		`/a\tb`:         `/a\\tb`,
+		"/not-utf8\xff": "/not-utf8\xff",
+	}
+	for in, want := range cases {
+		if got := escapePath(in); got != want {
+			t.Errorf("escapePath(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+// TestWarnfEscapes checks that a warning naming a path that holds a
+// newline is still one line.
+//
+//nolint:paralleltest // replaces the process-wide os.Stderr
+func TestWarnfEscapes(t *testing.T) {
+	f, err := os.Create(filepath.Join(t.TempDir(), "stderr"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	saved := os.Stderr
+	os.Stderr = f
+
+	t.Cleanup(func() {
+		os.Stderr = saved
+
+		_ = f.Close()
+	})
+
+	(&progress{}).warnf("stat %s: %s", "/d/a\nb", "gone")
+
+	_, err = f.Seek(0, io.SeekStart)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := io.ReadAll(f)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	want := `stat /d/a\nb: gone` + "\n"
+	if string(got) != want {
+		t.Errorf("warning = %q, want %q", got, want)
+	}
+}
+
 func TestCollectDupeGroups(t *testing.T) {
 	t.Parallel()
 

script/cibuild

@@ -16,10 +16,10 @@
 # implies the repo is green.
 #
 # That implication holds only because of CHECK_EPOCH. A COPY layer is
-# invalidated by changed content, and a merge commit's tree is
+# invalidated only by changed content, and a rebuild of an unchanged
-# byte-identical to the branch head it merges, so without a fresh value
+# checkout sends the same content, so without a fresh value here Docker
-# here Docker serves the gate layers from cache and the build reports a
+# serves the gate layers from cache and the build reports a green it
-# green it never earned. Passing the current epoch invalidates the gate
+# never earned. Passing the current epoch invalidates the gate
 # layers on every run while leaving the pinned base images and
 # go mod download cached; see the Dockerfile for the placement.
 set -eu

trees.go

@@ -62,7 +62,8 @@ func runTrees(ctx context.Context) error {
 		first := g[0]
 		for _, n := range g[1:] {
 			_, err = fmt.Fprintf(out, "%s\t%s\t%d\t%d\n",
-				first.path, n.path, first.fileCount, first.totalSize)
+				escapePath(first.path), escapePath(n.path),
+				first.fileCount, first.totalSize)
 			if err != nil {
 				return fmt.Errorf("write stdout: %w", err)
 			}
@@ -87,8 +88,8 @@ func runTrees(ctx context.Context) error {
 
 // buildHierarchy reconstructs the directory hierarchy from the record
 // paths under a synthetic super-root. Paths are split on "/"; for
-// absolute paths the first component is empty, which simply becomes a
+// absolute paths the first component is empty, which becomes the
-// top-level node representing "/". It returns the super-root and every
+// top-level node with path "/". It returns the super-root and every
 // directory node created.
 func buildHierarchy(recs []scanRec) (*treeNode, []*treeNode) {
 	super := &treeNode{}
@@ -102,9 +103,17 @@ func buildHierarchy(recs []scanRec) (*treeNode, []*treeNode) {
 		for _, c := range comps[:len(comps)-1] {
 			child := node.dirs[c]
 			if child == nil {
-				childPath := c
+				childPath := node.path + "/" + c
-				if node != super {
+
-					childPath = node.path + "/" + c
+				// The root directory's path is "/", not empty, and its
+				// children's paths start with one slash, not two.
+				switch {
+				case node == super && c == "":
+					childPath = "/"
+				case node == super:
+					childPath = c
+				case node.path == "/":
+					childPath = "/" + c
 				}
 
 				child = &treeNode{path: childPath, parent: node}

trees_test.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"bytes"
 	"slices"
 	"testing"
 )
@@ -84,6 +85,46 @@ func TestBuildHierarchyCounts(t *testing.T) {
 	}
 }
 
+func TestBuildHierarchyRootPath(t *testing.T) {
+	t.Parallel()
+
+	// The root directory's path is "/", never empty, and its
+	// children's paths start with a single slash.
+	_, dirs := buildHierarchy([]scanRec{{path: "/f"}, {path: "/srv/g"}})
+
+	got := make([]string, 0, len(dirs))
+	for _, d := range dirs {
+		got = append(got, d.path)
+	}
+
+	slices.Sort(got)
+
+	want := []string{"/", "/srv"}
+	if !slices.Equal(got, want) {
+		t.Fatalf("directory paths = %q, want %q", got, want)
+	}
+}
+
+func TestRunTreesEscapesPaths(t *testing.T) {
+	t.Setenv(databaseEnv, seedDatabase(t, awkwardPairRecs()))
+
+	var stderr bytes.Buffer
+
+	stdout := captureStdout(t)
+
+	code := run([]string{cmdTrees}, &stderr)
+	if code != exitOK {
+		t.Fatalf("run(trees) = %d, want %d; stderr: %s",
+			code, exitOK, stderr.String())
+	}
+
+	want := "first\tdupe\tfiles\tsize\n" +
+		`/d/\tone\ntwo\rthree\\four` + "\t/d/A\t1\t5\n"
+	if got := stdout(); got != want {
+		t.Errorf("stdout = %q, want %q", got, want)
+	}
+}
+
 func TestTreeDigests(t *testing.T) {
 	t.Parallel()