Keep a non-root user's database in the XDG state directory (closes #171)

Without SFDUPES_DATABASE, a user other than root now uses
sfdupes/db.sqlite under $XDG_STATE_HOME (~/.local/state by default),
which scan creates, instead of failing on /var/lib/sfdupes. Root keeps
/var/lib/sfdupes/db.sqlite. sfdupes --help and README say where the
database is. Adds github.com/adrg/xdg, the decided XDG library.

Model: opus-5-5

internal/sfdupes/cli.go

@@ -116,6 +116,13 @@ func run(args []string, stdout, stderr io.Writer) int {
 	}
 }
 
+// databaseHelp says in sfdupes --help where the database is.
+const databaseHelp = `The database is the file SFDUPES_DATABASE names.
+When that is unset or empty, root uses /var/lib/sfdupes/db.sqlite. Any
+other user uses sfdupes/db.sqlite in the XDG state directory:
+$XDG_STATE_HOME, or ~/.local/state when that is unset
+(~/Library/Application Support on macOS).`
+
 // newRootCommand builds the command tree. Everything on stdout is
 // machine-readable data, the version line included; all human-facing
 // output (help, usage, errors) goes to stderr.
@@ -134,9 +141,12 @@ func newRootCommand(stdout, stderr io.Writer) *cobra.Command {
 		return nil
 	})
 
+	short := "Find candidate duplicate files by size and head/tail/content SHA-256"
+
 	root := &cobra.Command{
 		Use:   "sfdupes",
-		Short: "Find candidate duplicate files by size and head/tail/content SHA-256",
+		Short: short,
+		Long:  short + ".\n\n" + databaseHelp,
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if showVersion {

internal/sfdupes/cli_test.go

@@ -15,6 +15,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/adrg/xdg"
 	"golang.org/x/sys/unix"
 )
 
@@ -553,13 +554,14 @@ func TestRunNamesDefaultDatabase(t *testing.T) {
 	// line.
 	t.Setenv(databaseEnv, "")
 
-	// Whether scan calls the database new depends on that machine too.
-	scanWant := "scan: database " + defaultDatabasePath + " (default)\n"
+	dbPath := defaultDatabasePath(os.Geteuid())
 
-	_, err := os.Stat(defaultDatabasePath)
+	// Whether scan calls the database new depends on that machine too.
+	scanWant := "scan: database " + dbPath + " (default)\n"
+
+	_, err := os.Stat(dbPath)
 	if errors.Is(err, fs.ErrNotExist) {
-		scanWant = "scan: new database " + defaultDatabasePath +
-			" (default)\n"
+		scanWant = "scan: new database " + dbPath + " (default)\n"
 	}
 
 	missing := filepath.Join(t.TempDir(), "nope")
@@ -578,21 +580,21 @@ func TestRunNamesDefaultDatabase(t *testing.T) {
 			run: func() error {
 				return runReport(cancelledContext(t), io.Discard)
 			},
-			want: "report: database " + defaultDatabasePath + " (default)\n" +
+			want: "report: database " + dbPath + " (default)\n" +
 				reportOpenLine + "\n" + reportOpenLine + "\n",
 		},
 		cmdTrees: {
 			run: func() error {
 				return runTrees(cancelledContext(t), io.Discard)
 			},
-			want: "trees: database " + defaultDatabasePath + " (default)\n" +
+			want: "trees: database " + dbPath + " (default)\n" +
 				treesOpenLine + "\n" + treesOpenLine + "\n",
 		},
 		cmdInfo: {
 			run: func() error {
 				return runInfo(cancelledContext(t), io.Discard)
 			},
-			want: "info: database " + defaultDatabasePath + " (default)\n" +
+			want: "info: database " + dbPath + " (default)\n" +
 				infoOpenLine + "\n" + infoOpenLine + "\n",
 		},
 	}
@@ -711,6 +713,20 @@ func TestRunHelp(t *testing.T) {
 			t.Errorf("run(%v) stdout = %q, want nothing (data only)",
 				args, got)
 		}
+
+		if args[0] == cmdScan {
+			continue
+		}
+
+		// README §Location: sfdupes --help says where the database is.
+		for _, want := range []string{
+			databaseEnv, rootDatabasePath, "XDG_STATE_HOME", "~/.local/state",
+		} {
+			if !strings.Contains(stderr.String(), want) {
+				t.Errorf("run(%v) stderr = %q, want it to name %q",
+					args, stderr.String(), want)
+			}
+		}
 	}
 }
 
@@ -1496,6 +1512,24 @@ func TestRunDatabasePathUsedAsGiven(t *testing.T) {
 	})
 }
 
+func TestRunNonRootUsesStateDirectory(t *testing.T) {
+	// README §Location: without SFDUPES_DATABASE, a user other than
+	// root keeps the database in the XDG state directory. scan creates
+	// the missing directories, and report and trees read the same file.
+	if os.Geteuid() == 0 {
+		t.Skip("root uses " + rootDatabasePath)
+	}
+
+	t.Cleanup(xdg.Reload)
+
+	state := t.TempDir()
+	t.Setenv("XDG_STATE_HOME", state)
+	t.Setenv(databaseEnv, "")
+	xdg.Reload()
+
+	assertRunsUseDatabase(t, filepath.Join(state, "sfdupes"), "db.sqlite")
+}
+
 // holdScanLock takes the lock on the database at path, as a running
 // scan does, and holds it until the test ends. It fails the test when
 // the lock is already held.

internal/sfdupes/db.go

@@ -15,15 +15,16 @@ import (
 	"strings"
 	"time"
 
+	"github.com/adrg/xdg"
 	"golang.org/x/sys/unix"
 	// The pure-Go SQLite driver, registered as "sqlite"; keeps cgo
 	// disabled.
 	_ "modernc.org/sqlite"
 )
 
-// defaultDatabasePath is where the persistent scan database lives when
-// SFDUPES_DATABASE is not set.
-const defaultDatabasePath = "/var/lib/sfdupes/db.sqlite"
+// rootDatabasePath is the database root uses when SFDUPES_DATABASE is
+// not set.
+const rootDatabasePath = "/var/lib/sfdupes/db.sqlite"
 
 // databaseEnv is the environment variable that overrides the database
 // path.
@@ -144,13 +145,27 @@ var errScanRunning = errors.New("another scan is running")
 // 32 bytes of a SHA-256.
 var errHashSize = errors.New("hash is not 32 bytes")
 
+// defaultDatabasePath is the database used when SFDUPES_DATABASE is not
+// set: rootDatabasePath for root (euid 0), and db.sqlite in the
+// directory sfdupes under the XDG state directory for any other user.
+// xdg reads XDG_STATE_HOME and HOME once, when the program starts. The
+// path is joined as text, not cleaned, for the reason absolutePath
+// gives.
+func defaultDatabasePath(euid int) string {
+	if euid == 0 {
+		return rootDatabasePath
+	}
+
+	return strings.TrimSuffix(xdg.StateHome, "/") + "/sfdupes/db.sqlite"
+}
+
 // databasePath resolves the database location: SFDUPES_DATABASE when
-// set and non-empty, the compiled-in default otherwise. It returns the
+// set and non-empty, defaultDatabasePath otherwise. It returns the
 // 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"
+	path, source := defaultDatabasePath(os.Geteuid()), "default"
 	if p := os.Getenv(databaseEnv); p != "" {
 		path, source = p, "from "+databaseEnv
 	}

internal/sfdupes/db_test.go

@@ -9,10 +9,13 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"runtime"
 	"slices"
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/adrg/xdg"
 )
 
 // testDBPath returns a database path inside a fresh temp dir, with
@@ -60,7 +63,7 @@ func TestDatabasePath(t *testing.T) {
 	cases := []struct {
 		env, path, source string
 	}{
-		{"", defaultDatabasePath, "default"},
+		{"", defaultDatabasePath(os.Geteuid()), "default"},
 		{"/custom/place.sqlite", "/custom/place.sqlite", fromEnv},
 		{"/custom/link/../place.sqlite", "/custom/link/../place.sqlite",
 			fromEnv},
@@ -89,6 +92,41 @@ func TestDatabasePath(t *testing.T) {
 	}
 }
 
+func TestDefaultDatabasePath(t *testing.T) {
+	// README §Location: root's database is /var/lib/sfdupes/db.sqlite.
+	// Any other user's is db.sqlite in sfdupes under XDG_STATE_HOME, or
+	// under ~/.local/state when XDG_STATE_HOME is unset or not absolute.
+	if runtime.GOOS != goosLinux {
+		t.Skip("macOS has another default state directory")
+	}
+
+	t.Cleanup(xdg.Reload)
+	t.Setenv("HOME", "/home/someone")
+
+	cases := []struct {
+		euid      int
+		stateHome string
+		want      string
+	}{
+		{0, "", rootDatabasePath},
+		{0, "/elsewhere/state", rootDatabasePath},
+		{1000, "", "/home/someone/.local/state/sfdupes/db.sqlite"},
+		{1000, "relative/state", "/home/someone/.local/state/sfdupes/db.sqlite"},
+		{1000, "/elsewhere/state", "/elsewhere/state/sfdupes/db.sqlite"},
+		{1000, "/elsewhere/state/", "/elsewhere/state/sfdupes/db.sqlite"},
+	}
+
+	for _, tc := range cases {
+		t.Setenv("XDG_STATE_HOME", tc.stateHome)
+		xdg.Reload()
+
+		if got := defaultDatabasePath(tc.euid); got != tc.want {
+			t.Errorf("defaultDatabasePath(%d) with XDG_STATE_HOME=%q = %q, want %q",
+				tc.euid, tc.stateHome, got, tc.want)
+		}
+	}
+}
+
 func TestOpenScanDatabaseCreates(t *testing.T) {
 	t.Parallel()