feat: split XDG data/state dirs and add Windows legacy migration

Separate backups/trash into XDG_DATA_HOME and logs into XDG_STATE_HOME
instead of keeping everything under XDG_CONFIG_HOME. Add automatic
migration at startup to move existing data to the new locations.

Fix Windows path resolution: DataDir() and StateDir() now fall back to
%AppData% on Windows (matching BaseDir()), preventing incorrect use of
~/.local/share and ~/.local/state paths.

Add MigrateWindowsLegacyDir() to move pre-v0.13.0 data from
~\.config\skillshare\ to %AppData%\skillshare\ on Windows.

Update doctor, oplog, backup, trash, and all tests/docs accordingly.
This commit is contained in:
Willie
2026-02-16 10:41:14 +08:00
parent 41e822d979
commit 0bf84493cc
31 changed files with 469 additions and 99 deletions
+7 -6
View File
@@ -12,6 +12,7 @@ import (
"strings"
"time"
"skillshare/internal/backup"
"skillshare/internal/config"
"skillshare/internal/sync"
"skillshare/internal/trash"
@@ -76,7 +77,9 @@ func cmdDoctorGlobal() error {
return nil
}
ui.Success("Config: %s", config.ConfigPath())
ui.Info("Base directory: %s", config.BaseDir())
ui.Info("Config directory: %s", config.BaseDir())
ui.Info("Data directory: %s", config.DataDir())
ui.Info("State directory: %s", config.StateDir())
cfg, err := config.Load()
if err != nil {
@@ -85,7 +88,7 @@ func cmdDoctorGlobal() error {
}
runDoctorChecks(cfg, result, false)
checkBackupStatus(false, config.ConfigPath())
checkBackupStatus(false, backup.BackupDir())
checkTrashStatus(trash.TrashDir())
checkVersionDoctor(cfg)
checkForUpdates()
@@ -119,7 +122,7 @@ func cmdDoctorProject(root string) error {
}
runDoctorChecks(cfg, result, true)
checkBackupStatus(true, cfgPath)
checkBackupStatus(true, "")
checkTrashStatus(trash.ProjectTrashDir(root))
checkVersionDoctor(cfg)
checkForUpdates()
@@ -569,13 +572,11 @@ func checkDuplicateSkills(cfg *config.Config, result *doctorResult) {
}
// checkBackupStatus shows last backup time
func checkBackupStatus(isProject bool, cfgPath string) {
func checkBackupStatus(isProject bool, backupDir string) {
if isProject {
ui.Info("Backups: not used in project mode")
return
}
backupDir := filepath.Join(filepath.Dir(cfgPath), "backups")
entries, err := os.ReadDir(backupDir)
if err != nil || len(entries) == 0 {
ui.Info("Backups: none found")
+7
View File
@@ -6,6 +6,7 @@ import (
"path/filepath"
"runtime"
"skillshare/internal/config"
"skillshare/internal/ui"
versioncheck "skillshare/internal/version"
)
@@ -44,6 +45,12 @@ func main() {
// Clean up any leftover .old files from Windows self-upgrade
cleanupOldBinary()
// Migrate Windows legacy ~/.config/skillshare → %AppData%\skillshare
config.MigrateWindowsLegacyDir()
// Migrate legacy dirs (backups/trash/logs) to XDG data/state dirs
config.MigrateXDGDirs()
// Set version for other packages to use
versioncheck.Version = version
+1 -1
View File
@@ -13,7 +13,7 @@ import (
// BackupDir returns the backup directory path.
func BackupDir() string {
return filepath.Join(config.BaseDir(), "backups")
return filepath.Join(config.DataDir(), "backups")
}
// Create creates a backup of the target directory
+3 -4
View File
@@ -127,12 +127,11 @@ func TestCopyDir_EmptyDir(t *testing.T) {
}
}
func TestBackupDir_RespectsXDGConfigHome(t *testing.T) {
t.Setenv("XDG_CONFIG_HOME", "/custom/config")
t.Setenv("SKILLSHARE_CONFIG", "")
func TestBackupDir_RespectsXDGDataHome(t *testing.T) {
t.Setenv("XDG_DATA_HOME", "/custom/data")
got := BackupDir()
want := filepath.Join("/custom/config", "skillshare", "backups")
want := filepath.Join("/custom/data", "skillshare", "backups")
if got != want {
t.Errorf("BackupDir() = %q, want %q", got, want)
}
+36
View File
@@ -67,6 +67,42 @@ func BaseDir() string {
return filepath.Join(home, ".config", "skillshare")
}
// DataDir returns the data directory (XDG_DATA_HOME).
// Priority:
// 1. $XDG_DATA_HOME/skillshare (any platform, if set)
// 2. %AppData%/skillshare (Windows only, via os.UserConfigDir())
// 3. ~/.local/share/skillshare (Linux, macOS)
func DataDir() string {
if xdg := os.Getenv("XDG_DATA_HOME"); xdg != "" {
return filepath.Join(xdg, "skillshare")
}
if runtime.GOOS == "windows" {
if dir, err := os.UserConfigDir(); err == nil {
return filepath.Join(dir, "skillshare")
}
}
home, _ := os.UserHomeDir()
return filepath.Join(home, ".local", "share", "skillshare")
}
// StateDir returns the state directory (XDG_STATE_HOME).
// Priority:
// 1. $XDG_STATE_HOME/skillshare (any platform, if set)
// 2. %AppData%/skillshare (Windows only, via os.UserConfigDir())
// 3. ~/.local/state/skillshare (Linux, macOS)
func StateDir() string {
if xdg := os.Getenv("XDG_STATE_HOME"); xdg != "" {
return filepath.Join(xdg, "skillshare")
}
if runtime.GOOS == "windows" {
if dir, err := os.UserConfigDir(); err == nil {
return filepath.Join(dir, "skillshare")
}
}
home, _ := os.UserHomeDir()
return filepath.Join(home, ".local", "state", "skillshare")
}
// ConfigPath returns the config file path, respecting SKILLSHARE_CONFIG env var
func ConfigPath() string {
// Allow override for testing
+49
View File
@@ -0,0 +1,49 @@
package config
import (
"os"
"path/filepath"
"testing"
)
func TestDataDir_DefaultFallback(t *testing.T) {
t.Setenv("XDG_DATA_HOME", "")
home, _ := os.UserHomeDir()
got := DataDir()
want := filepath.Join(home, ".local", "share", "skillshare")
if got != want {
t.Errorf("DataDir() = %q, want %q", got, want)
}
}
func TestDataDir_RespectsXDGDataHome(t *testing.T) {
t.Setenv("XDG_DATA_HOME", "/custom/data")
got := DataDir()
want := filepath.Join("/custom/data", "skillshare")
if got != want {
t.Errorf("DataDir() = %q, want %q", got, want)
}
}
func TestStateDir_DefaultFallback(t *testing.T) {
t.Setenv("XDG_STATE_HOME", "")
home, _ := os.UserHomeDir()
got := StateDir()
want := filepath.Join(home, ".local", "state", "skillshare")
if got != want {
t.Errorf("StateDir() = %q, want %q", got, want)
}
}
func TestStateDir_RespectsXDGStateHome(t *testing.T) {
t.Setenv("XDG_STATE_HOME", "/custom/state")
got := StateDir()
want := filepath.Join("/custom/state", "skillshare")
if got != want {
t.Errorf("StateDir() = %q, want %q", got, want)
}
}
+55
View File
@@ -0,0 +1,55 @@
package config
import (
"os"
"path/filepath"
"runtime"
)
// MigrateWindowsLegacyDir moves the entire ~/.config/skillshare directory to
// %AppData%\skillshare on Windows. This handles upgrades from pre-v0.13.0 where
// Windows incorrectly used the Unix-style ~/.config/ path.
// No-op on non-Windows platforms or if legacy dir doesn't exist.
func MigrateWindowsLegacyDir() {
if runtime.GOOS != "windows" {
return
}
home, err := os.UserHomeDir()
if err != nil {
return
}
oldDir := filepath.Join(home, ".config", "skillshare")
newDir := BaseDir() // %AppData%\skillshare on Windows
if oldDir == newDir {
return // XDG_CONFIG_HOME points to ~/.config, no migration needed
}
migrateDir(oldDir, newDir)
}
// MigrateXDGDirs moves backups/trash/logs from legacy config dir to proper XDG dirs.
// Called once at startup. No-op if already migrated or no legacy data exists.
func MigrateXDGDirs() {
base := BaseDir()
moves := []struct{ old, new string }{
{filepath.Join(base, "backups"), filepath.Join(DataDir(), "backups")},
{filepath.Join(base, "trash"), filepath.Join(DataDir(), "trash")},
{filepath.Join(base, "logs"), filepath.Join(StateDir(), "logs")},
}
for _, m := range moves {
if m.old == m.new {
continue // XDG vars resolve to same location
}
migrateDir(m.old, m.new)
}
}
func migrateDir(oldPath, newPath string) {
if _, err := os.Stat(oldPath); os.IsNotExist(err) {
return // nothing to migrate
}
if _, err := os.Stat(newPath); err == nil {
return // destination already exists
}
os.MkdirAll(filepath.Dir(newPath), 0755)
os.Rename(oldPath, newPath)
}
+169
View File
@@ -0,0 +1,169 @@
package config
import (
"os"
"path/filepath"
"runtime"
"testing"
)
func TestMigrateXDGDirs_MovesLegacyDirs(t *testing.T) {
tmp := t.TempDir()
configHome := filepath.Join(tmp, "config")
dataHome := filepath.Join(tmp, "data")
stateHome := filepath.Join(tmp, "state")
t.Setenv("XDG_CONFIG_HOME", configHome)
t.Setenv("XDG_DATA_HOME", dataHome)
t.Setenv("XDG_STATE_HOME", stateHome)
// Create legacy directories with content
legacyBackups := filepath.Join(configHome, "skillshare", "backups")
legacyTrash := filepath.Join(configHome, "skillshare", "trash")
legacyLogs := filepath.Join(configHome, "skillshare", "logs")
os.MkdirAll(legacyBackups, 0755)
os.WriteFile(filepath.Join(legacyBackups, "backup1.tar"), []byte("data"), 0644)
os.MkdirAll(legacyTrash, 0755)
os.WriteFile(filepath.Join(legacyTrash, "trashed"), []byte("data"), 0644)
os.MkdirAll(legacyLogs, 0755)
os.WriteFile(filepath.Join(legacyLogs, "ops.log"), []byte("data"), 0644)
MigrateXDGDirs()
// Verify moved to new locations
newBackups := filepath.Join(dataHome, "skillshare", "backups")
newTrash := filepath.Join(dataHome, "skillshare", "trash")
newLogs := filepath.Join(stateHome, "skillshare", "logs")
if _, err := os.Stat(filepath.Join(newBackups, "backup1.tar")); err != nil {
t.Errorf("backups not migrated: %v", err)
}
if _, err := os.Stat(filepath.Join(newTrash, "trashed")); err != nil {
t.Errorf("trash not migrated: %v", err)
}
if _, err := os.Stat(filepath.Join(newLogs, "ops.log")); err != nil {
t.Errorf("logs not migrated: %v", err)
}
// Verify legacy dirs removed
if _, err := os.Stat(legacyBackups); !os.IsNotExist(err) {
t.Error("legacy backups dir should be removed after migration")
}
if _, err := os.Stat(legacyTrash); !os.IsNotExist(err) {
t.Error("legacy trash dir should be removed after migration")
}
if _, err := os.Stat(legacyLogs); !os.IsNotExist(err) {
t.Error("legacy logs dir should be removed after migration")
}
}
func TestMigrateXDGDirs_NoopWhenNoLegacyDirs(t *testing.T) {
tmp := t.TempDir()
t.Setenv("XDG_CONFIG_HOME", filepath.Join(tmp, "config"))
t.Setenv("XDG_DATA_HOME", filepath.Join(tmp, "data"))
t.Setenv("XDG_STATE_HOME", filepath.Join(tmp, "state"))
// No legacy dirs exist — should not panic or error
MigrateXDGDirs()
}
func TestMigrateXDGDirs_SkipsWhenDestExists(t *testing.T) {
tmp := t.TempDir()
configHome := filepath.Join(tmp, "config")
dataHome := filepath.Join(tmp, "data")
stateHome := filepath.Join(tmp, "state")
t.Setenv("XDG_CONFIG_HOME", configHome)
t.Setenv("XDG_DATA_HOME", dataHome)
t.Setenv("XDG_STATE_HOME", stateHome)
// Create both legacy and new backups dir
legacyBackups := filepath.Join(configHome, "skillshare", "backups")
newBackups := filepath.Join(dataHome, "skillshare", "backups")
os.MkdirAll(legacyBackups, 0755)
os.WriteFile(filepath.Join(legacyBackups, "old.tar"), []byte("old"), 0644)
os.MkdirAll(newBackups, 0755)
os.WriteFile(filepath.Join(newBackups, "new.tar"), []byte("new"), 0644)
MigrateXDGDirs()
// New dir should be untouched
data, err := os.ReadFile(filepath.Join(newBackups, "new.tar"))
if err != nil || string(data) != "new" {
t.Error("existing new dir should not be overwritten")
}
// Legacy dir should still exist (not removed since dest already existed)
if _, err := os.Stat(legacyBackups); os.IsNotExist(err) {
t.Error("legacy dir should remain when dest already exists")
}
}
// TestMigrateWindowsLegacyDir_UsesMigrateDir tests the underlying migrateDir
// logic that MigrateWindowsLegacyDir delegates to. We can't test the actual
// function on non-Windows (it early-returns), so we test the migration path directly.
func TestMigrateWindowsLegacyDir_MigrationPath(t *testing.T) {
tmp := t.TempDir()
oldDir := filepath.Join(tmp, ".config", "skillshare")
newDir := filepath.Join(tmp, "AppData", "skillshare")
// Create legacy dir with config and skills
os.MkdirAll(filepath.Join(oldDir, "skills"), 0755)
os.WriteFile(filepath.Join(oldDir, "config.yaml"), []byte("source: skills"), 0644)
os.WriteFile(filepath.Join(oldDir, "skills", "SKILL.md"), []byte("# skill"), 0644)
// Simulate what MigrateWindowsLegacyDir does: migrateDir(old, new)
migrateDir(oldDir, newDir)
// Verify moved
data, err := os.ReadFile(filepath.Join(newDir, "config.yaml"))
if err != nil || string(data) != "source: skills" {
t.Errorf("config.yaml not migrated: %v", err)
}
if _, err := os.Stat(filepath.Join(newDir, "skills", "SKILL.md")); err != nil {
t.Errorf("skills dir not migrated: %v", err)
}
// Verify old dir removed
if _, err := os.Stat(oldDir); !os.IsNotExist(err) {
t.Error("legacy dir should be removed after migration")
}
}
func TestMigrateWindowsLegacyDir_SkipsOnNonWindows(t *testing.T) {
if runtime.GOOS == "windows" {
t.Skip("this test verifies non-Windows no-op behavior")
}
// Should not panic or do anything on non-Windows
MigrateWindowsLegacyDir()
}
func TestMigrateWindowsLegacyDir_SkipsWhenDestExists(t *testing.T) {
tmp := t.TempDir()
oldDir := filepath.Join(tmp, ".config", "skillshare")
newDir := filepath.Join(tmp, "AppData", "skillshare")
os.MkdirAll(oldDir, 0755)
os.WriteFile(filepath.Join(oldDir, "config.yaml"), []byte("old"), 0644)
os.MkdirAll(newDir, 0755)
os.WriteFile(filepath.Join(newDir, "config.yaml"), []byte("new"), 0644)
migrateDir(oldDir, newDir)
// New dir untouched
data, _ := os.ReadFile(filepath.Join(newDir, "config.yaml"))
if string(data) != "new" {
t.Error("existing dest should not be overwritten")
}
// Old dir still exists
if _, err := os.Stat(oldDir); os.IsNotExist(err) {
t.Error("legacy dir should remain when dest already exists")
}
}
+8 -3
View File
@@ -9,6 +9,7 @@ import (
"path/filepath"
"time"
"skillshare/internal/config"
"skillshare/internal/install"
)
@@ -28,10 +29,14 @@ type Entry struct {
}
// LogDir returns the logs directory derived from a config file path.
// For global mode: ~/.config/skillshare/logs/
// For project mode: .skillshare/logs/
// For project mode: .skillshare/logs/ (alongside project config)
// For global mode: $XDG_STATE_HOME/skillshare/logs/
func LogDir(configPath string) string {
return filepath.Join(filepath.Dir(configPath), "logs")
configDir := filepath.Dir(configPath)
if filepath.Base(configDir) == ".skillshare" {
return filepath.Join(configDir, "logs")
}
return filepath.Join(config.StateDir(), "logs")
}
// Write appends a single JSONL entry to the named log file.
+15 -3
View File
@@ -11,14 +11,26 @@ import (
func tempConfigPath(t *testing.T) string {
t.Helper()
dir := t.TempDir()
// Isolate XDG_STATE_HOME so global-mode LogDir() doesn't collide across tests
t.Setenv("XDG_STATE_HOME", filepath.Join(dir, "state"))
return filepath.Join(dir, "config.yaml")
}
func TestLogDir(t *testing.T) {
func TestLogDir_Global(t *testing.T) {
t.Setenv("XDG_STATE_HOME", "/custom/state")
got := LogDir("/home/user/.config/skillshare/config.yaml")
want := "/home/user/.config/skillshare/logs"
want := "/custom/state/skillshare/logs"
if got != want {
t.Errorf("LogDir() = %q, want %q", got, want)
t.Errorf("LogDir(global) = %q, want %q", got, want)
}
}
func TestLogDir_Project(t *testing.T) {
got := LogDir("/project/.skillshare/config.yaml")
want := "/project/.skillshare/logs"
if got != want {
t.Errorf("LogDir(project) = %q, want %q", got, want)
}
}
+3 -1
View File
@@ -58,7 +58,9 @@ func NewSandbox(t *testing.T) *Sandbox {
dirs := []string{
filepath.Join(home, ".config", "skillshare"),
filepath.Join(home, ".config", "skillshare", "skills"),
filepath.Join(home, ".config", "skillshare", "backups"),
filepath.Join(home, ".local", "share", "skillshare", "backups"),
filepath.Join(home, ".local", "share", "skillshare", "trash"),
filepath.Join(home, ".local", "state", "skillshare", "logs"),
filepath.Join(home, ".claude"),
filepath.Join(home, ".codex"),
filepath.Join(home, ".cursor"),
+1 -1
View File
@@ -15,7 +15,7 @@ const defaultMaxAge = 7 * 24 * time.Hour // 7 days
// TrashDir returns the global trash directory path.
func TrashDir() string {
return filepath.Join(config.BaseDir(), "trash")
return filepath.Join(config.DataDir(), "trash")
}
// ProjectTrashDir returns the project-level trash directory path.
+3 -4
View File
@@ -5,12 +5,11 @@ import (
"testing"
)
func TestTrashDir_RespectsXDGConfigHome(t *testing.T) {
t.Setenv("XDG_CONFIG_HOME", "/custom/config")
t.Setenv("SKILLSHARE_CONFIG", "")
func TestTrashDir_RespectsXDGDataHome(t *testing.T) {
t.Setenv("XDG_DATA_HOME", "/custom/data")
got := TrashDir()
want := filepath.Join("/custom/config", "skillshare", "trash")
want := filepath.Join("/custom/data", "skillshare", "trash")
if got != want {
t.Errorf("TrashDir() = %q, want %q", got, want)
}
+3 -3
View File
@@ -48,7 +48,7 @@ targets:
backupResult.AssertSuccess(t)
// Verify backup contains local skill but not the symlinked one
backupDir := filepath.Join(sb.Home, ".config", "skillshare", "backups")
backupDir := filepath.Join(sb.Home, ".local", "share", "skillshare", "backups")
entries, err := os.ReadDir(backupDir)
if err != nil || len(entries) == 0 {
t.Fatal("backup directory should contain a timestamp directory")
@@ -233,7 +233,7 @@ targets:
result.AssertSuccess(t)
result.AssertOutputContains(t, "Dry run")
backupDir := filepath.Join(sb.Home, ".config", "skillshare", "backups")
backupDir := filepath.Join(sb.Home, ".local", "share", "skillshare", "backups")
entries, err := os.ReadDir(backupDir)
if err != nil {
t.Fatalf("failed to read backup dir: %v", err)
@@ -251,7 +251,7 @@ func TestBackup_CleanupDryRun_DoesNotRemoveBackups(t *testing.T) {
targets: {}
`)
backupRoot := filepath.Join(sb.Home, ".config", "skillshare", "backups")
backupRoot := filepath.Join(sb.Home, ".local", "share", "skillshare", "backups")
timestampDir := filepath.Join(backupRoot, "2024-01-01_00-00-00")
backupPath := filepath.Join(timestampDir, "claude", "old-skill")
os.MkdirAll(backupPath, 0755)
+1 -1
View File
@@ -191,7 +191,7 @@ targets:
sb.RunCLI("sync")
// Check the log file exists and is valid JSONL
logDir := filepath.Join(filepath.Dir(sb.ConfigPath), "logs")
logDir := filepath.Join(sb.Home, ".local", "state", "skillshare", "logs")
logFile := filepath.Join(logDir, "operations.log")
data, err := os.ReadFile(logFile)
+4 -4
View File
@@ -64,7 +64,7 @@ func TestRestore_FromLatest_RestoresBackup(t *testing.T) {
targetPath := sb.CreateTarget("claude")
// Create backup directory manually
backupDir := filepath.Join(sb.Home, ".config", "skillshare", "backups")
backupDir := filepath.Join(sb.Home, ".local", "share", "skillshare", "backups")
timestamp := time.Now().Format("20060102-150405")
backupPath := filepath.Join(backupDir, timestamp, "claude")
os.MkdirAll(backupPath, 0755)
@@ -99,7 +99,7 @@ func TestRestore_FromTimestamp_RestoresSpecific(t *testing.T) {
targetPath := sb.CreateTarget("claude")
// Create backup directory manually with specific timestamp
backupDir := filepath.Join(sb.Home, ".config", "skillshare", "backups")
backupDir := filepath.Join(sb.Home, ".local", "share", "skillshare", "backups")
timestamp := "20240101-120000"
backupPath := filepath.Join(backupDir, timestamp, "claude")
os.MkdirAll(backupPath, 0755)
@@ -132,7 +132,7 @@ func TestRestore_OverwritesSymlink(t *testing.T) {
os.Symlink(sb.SourcePath, targetPath)
// Create backup
backupDir := filepath.Join(sb.Home, ".config", "skillshare", "backups")
backupDir := filepath.Join(sb.Home, ".local", "share", "skillshare", "backups")
timestamp := time.Now().Format("20060102-150405")
backupPath := filepath.Join(backupDir, timestamp, "claude")
os.MkdirAll(backupPath, 0755)
@@ -163,7 +163,7 @@ func TestRestore_DryRun_DoesNotRestore(t *testing.T) {
targetPath := sb.CreateTarget("claude")
backupDir := filepath.Join(sb.Home, ".config", "skillshare", "backups")
backupDir := filepath.Join(sb.Home, ".local", "share", "skillshare", "backups")
timestamp := time.Now().Format("20060102-150405")
backupPath := filepath.Join(backupDir, timestamp, "claude")
os.MkdirAll(backupPath, 0755)
+1 -1
View File
@@ -69,7 +69,7 @@ targets: {}
}
// Trash should be empty now
trashDir := filepath.Join(sb.Home, ".config", "skillshare", "trash")
trashDir := filepath.Join(sb.Home, ".local", "share", "skillshare", "trash")
entries, _ := os.ReadDir(trashDir)
if len(entries) != 0 {
t.Errorf("trash should be empty after restore, has %d entries", len(entries))
-1
View File
@@ -59,4 +59,3 @@ func TestUI_ClearCache(t *testing.T) {
t.Error("expected UI cache directory to be removed after --clear-cache")
}
}
+5 -4
View File
@@ -30,7 +30,7 @@ targets: {}
}
// Trash directory should contain the skill
trashDir := filepath.Join(sb.Home, ".config", "skillshare", "trash")
trashDir := filepath.Join(sb.Home, ".local", "share", "skillshare", "trash")
entries, err := os.ReadDir(trashDir)
if err != nil {
t.Fatalf("trash directory should exist: %v", err)
@@ -115,8 +115,9 @@ targets: {}
}
// Trash should be empty
trashDir := filepath.Join(sb.Home, ".config", "skillshare", "trash")
if _, err := os.Stat(trashDir); err == nil {
t.Error("trash directory should not be created during dry-run")
trashDir := filepath.Join(sb.Home, ".local", "share", "skillshare", "trash")
entries, err := os.ReadDir(trashDir)
if err == nil && len(entries) > 0 {
t.Error("trash directory should be empty during dry-run")
}
}
+2 -2
View File
@@ -84,8 +84,8 @@ func TestXDG_Doctor_ShowsBaseDirectory(t *testing.T) {
t.Fatalf("doctor failed: %s", result.Output())
}
if !strings.Contains(result.Output(), "Base directory") {
t.Error("doctor output should contain 'Base directory'")
if !strings.Contains(result.Output(), "Config directory") {
t.Error("doctor output should contain 'Config directory'")
}
}
+2 -2
View File
@@ -19,7 +19,7 @@ Backups are created **automatically** before:
- `skillshare sync`
- `skillshare target remove`
Location: `~/.config/skillshare/backups/<timestamp>/`
Location: `~/.local/share/skillshare/backups/<timestamp>/`
## Commands
@@ -68,7 +68,7 @@ Default cleanup policy:
## Backup Structure
```
~/.config/skillshare/backups/
~/.local/share/skillshare/backups/
├── 2026-01-20_15-30-00/
│ ├── claude/
│ │ ├── skill-a/
+12 -12
View File
@@ -72,11 +72,11 @@ skillshare log --json --cmd sync # Filtered JSONL
## Example Output
```
┌─ skillshare log ───────────────────────────────┐
│ Operations (last 2) │
│ mode: global │
│ file: ~/.config/skillshare/logs/operations.log │
└────────────────────────────────────────────────┘
┌─ skillshare log ────────────────────────────────────┐
│ Operations (last 2) │
│ mode: global │
│ file: ~/.local/state/skillshare/logs/operations.log │
└─────────────────────────────────────────────────────┘
TIME | CMD | STATUS | DUR
-----------------+-----------+---------+--------
2026-02-10 14:31 | SYNC | error | 0.8s
@@ -88,11 +88,11 @@ skillshare log --json --cmd sync # Filtered JSONL
targets: 3
scope: global
┌─ skillshare log ───────────────────────────────┐
│ Audit (last 1) │
│ mode: global │
│ file: ~/.config/skillshare/logs/audit.log │
└────────────────────────────────────────────────┘
┌─ skillshare log ────────────────────────────────────┐
│ Audit (last 1) │
│ mode: global │
│ file: ~/.local/state/skillshare/logs/audit.log │
└─────────────────────────────────────────────────────┘
TIME | CMD | STATUS | DUR
-----------------+-----------+---------+--------
2026-02-10 14:36 | AUDIT | blocked | 1.1s
@@ -125,8 +125,8 @@ Entries are stored in JSONL format (one JSON object per line):
## Log Location
```
~/.config/skillshare/logs/operations.log # Global operations
~/.config/skillshare/logs/audit.log # Global audit
~/.local/state/skillshare/logs/operations.log # Global operations
~/.local/state/skillshare/logs/audit.log # Global audit
<project>/.skillshare/logs/operations.log # Project operations
<project>/.skillshare/logs/audit.log # Project audit
```
+2 -2
View File
@@ -98,7 +98,7 @@ skillshare sync -n # Short form
▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. Backup targets (automatic) │
│ → ~/.config/skillshare/backups/2026-01-20_15-30-00/ │
│ → ~/.local/share/skillshare/backups/2026-01-20_15-30-00/ │
└─────────────────────────────────────────────────────────────────┘
│
▼
@@ -373,7 +373,7 @@ skillshare sync # Apply change
Backups are created **automatically** before `sync` and `target remove`.
Location: `~/.config/skillshare/backups/<timestamp>/`
Location: `~/.local/share/skillshare/backups/<timestamp>/`
### Manual Backup
+1 -1
View File
@@ -82,7 +82,7 @@ These two safety mechanisms protect different things:
| | backup | trash |
|---|---|---|
| **Protects** | target directories (sync snapshots) | source skills (uninstall) |
| **Location** | `~/.config/skillshare/backups/` | `~/.config/skillshare/trash/` |
| **Location** | `~/.local/share/skillshare/backups/` | `~/.local/share/skillshare/trash/` |
| **Triggered by** | `sync`, `target remove` | `uninstall` |
| **Restore with** | `skillshare restore <target>` | `skillshare trash restore <name>` |
| **Auto-cleanup** | manual (`backup --cleanup`) | 7 days |
+3 -3
View File
@@ -36,7 +36,7 @@ skillshare uninstall my-skill --force # Skip confirmation
▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Move to trash (kept 7 days) │
│ → ~/.config/skillshare/trash/my-skill_<timestamp>/ │
│ → ~/.local/share/skillshare/trash/my-skill_<timestamp>/ │
└─────────────────────────────────────────────────────────────────┘
```
@@ -82,14 +82,14 @@ skillshare uninstall my-skill --force
Uninstalled skills are **moved to trash**, not permanently deleted:
- **Location:** `~/.config/skillshare/trash/` (global) or `.skillshare/trash/` (project)
- **Location:** `~/.local/share/skillshare/trash/` (global) or `.skillshare/trash/` (project)
- **Retention:** 7 days, then automatically cleaned up
- **Reinstall hint:** If the skill was installed from a remote source, the reinstall command is shown
- **Restore:** Use `skillshare trash restore <name>` to recover from trash
```
✓ Uninstalled: my-skill
ℹ Moved to trash (7 days): ~/.config/skillshare/trash/my-skill_2026-01-20_15-30-00
ℹ Moved to trash (7 days): ~/.local/share/skillshare/trash/my-skill_2026-01-20_15-30-00
ℹ Reinstall: skillshare install github.com/user/repo/my-skill
```
@@ -133,8 +133,8 @@ make sandbox-down
|------|-------------|
| `~/.config/skillshare/config.yaml` | Configuration file |
| `~/.config/skillshare/skills/` | Source directory |
| `~/.config/skillshare/logs/` | Operation and audit logs |
| `~/.config/skillshare/backups/` | Backup directory |
| `~/.local/state/skillshare/logs/` | Operation and audit logs |
| `~/.local/share/skillshare/backups/` | Backup directory |
---
@@ -45,6 +45,36 @@ If you set `XDG_CONFIG_HOME` after initial setup, move your existing `~/.config/
---
### XDG_DATA_HOME
Override the data directory (backups, trash).
```bash
export XDG_DATA_HOME=~/my-data
# skillshare will use ~/my-data/skillshare/backups/ and ~/my-data/skillshare/trash/
```
**Default:** `~/.local/share/skillshare/`
---
### XDG_STATE_HOME
Override the state directory (operation logs).
```bash
export XDG_STATE_HOME=~/my-state
# skillshare will use ~/my-state/skillshare/logs/
```
**Default:** `~/.local/state/skillshare/`
:::tip Automatic migration
Starting from v0.13.0, skillshare follows the XDG Base Directory Specification for backups, trash, and logs. If you're upgrading from an older version, these directories are automatically migrated from `~/.config/skillshare/` to their proper XDG locations on first run.
:::
---
## GitHub API
### GITHUB_TOKEN
@@ -129,6 +159,8 @@ export GITHUB_TOKEN="ghp_your_token_here"
|----------|---------|---------|
| `SKILLSHARE_CONFIG` | Config file path | `~/.config/skillshare/config.yaml` |
| `XDG_CONFIG_HOME` | Base config directory | `~/.config` (Linux/macOS), `%AppData%` (Windows) |
| `XDG_DATA_HOME` | Data directory (backups, trash) | `~/.local/share` |
| `XDG_STATE_HOME` | State directory (logs) | `~/.local/state` |
| `GITHUB_TOKEN` | GitHub API auth | None |
| `SKILLSHARE_TEST_BINARY` | Test binary path | `bin/skillshare` |
+30 -26
View File
@@ -9,26 +9,25 @@ Directory layout and file locations for skillshare.
## Overview
```
~/.config/skillshare/
~/.config/skillshare/ # XDG_CONFIG_HOME
├── config.yaml # Configuration file
├── audit-rules.yaml # Custom audit rules (optional)
├── skills/ # Source directory
│ ├── my-skill/ # Regular skill
│ │ ├── SKILL.md # Skill definition (required)
│ │ └── .skillshare-meta.json # Install metadata (auto-generated)
│ ├── code-review/ # Another skill
│ │ └── SKILL.md
│ └── _team-skills/ # Tracked repository
│ ├── .git/ # Git history preserved
│ ├── frontend/
│ │ └── ui/
│ │ └── SKILL.md
│ └── backend/
│ └── api/
│ └── SKILL.md
├── logs/ # Operation logs (JSONL)
│ ├── operations.log # install, sync, update, etc.
│ └── audit.log # Security audit scans
└── skills/ # Source directory
├── my-skill/ # Regular skill
│ ├── SKILL.md # Skill definition (required)
│ └── .skillshare-meta.json # Install metadata (auto-generated)
├── code-review/ # Another skill
│ └── SKILL.md
└── _team-skills/ # Tracked repository
├── .git/ # Git history preserved
├── frontend/
│ └── ui/
│ └── SKILL.md
└── backend/
└── api/
└── SKILL.md
~/.local/share/skillshare/ # XDG_DATA_HOME
├── backups/ # Backup directory
│ ├── 2026-01-20_15-30-00/
│ │ ├── claude/
@@ -40,6 +39,11 @@ Directory layout and file locations for skillshare.
│ └── SKILL.md
└── old-skill_2026-01-19_10-00-00/
└── SKILL.md
~/.local/state/skillshare/ # XDG_STATE_HOME
└── logs/ # Operation logs (JSONL)
├── operations.log # install, sync, update, etc.
└── audit.log # Security audit scans
```
---
@@ -156,7 +160,7 @@ Metadata about where the skill was installed from:
### Location
```
~/.config/skillshare/backups/
~/.local/share/skillshare/backups/
```
### Structure
@@ -182,7 +186,7 @@ Backups are created:
### Location
```
~/.config/skillshare/trash/
~/.local/share/skillshare/trash/
```
**Project mode:**
@@ -211,7 +215,7 @@ Trashed skills are:
### Location
```
~/.config/skillshare/logs/
~/.local/state/skillshare/logs/
```
**Project mode:**
@@ -282,8 +286,8 @@ _team-skills__frontend__ui/SKILL.md
## Platform Differences
:::tip XDG_CONFIG_HOME
On any platform, setting `XDG_CONFIG_HOME` overrides the base directory. All paths below become relative to `$XDG_CONFIG_HOME/skillshare/` instead.
:::tip XDG Base Directory
skillshare respects the XDG Base Directory Specification. Override base directories with `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_STATE_HOME`.
See [Environment Variables](./environment-variables.md#xdg_config_home) for details.
:::
@@ -294,9 +298,9 @@ See [Environment Variables](./environment-variables.md#xdg_config_home) for deta
|------|------|
| Config | `~/.config/skillshare/config.yaml` |
| Source | `~/.config/skillshare/skills/` |
| Logs | `~/.config/skillshare/logs/` |
| Backups | `~/.config/skillshare/backups/` |
| Trash | `~/.config/skillshare/trash/` |
| Logs | `~/.local/state/skillshare/logs/` |
| Backups | `~/.local/share/skillshare/backups/` |
| Trash | `~/.local/share/skillshare/trash/` |
| Link type | Symlinks |
### Windows
+1 -1
View File
@@ -23,7 +23,7 @@ Technical reference documentation for skillshare.
|------|---------|
| `~/.config/skillshare/config.yaml` | Configuration file |
| `~/.config/skillshare/skills/` | Source directory |
| `~/.config/skillshare/backups/` | Backup directory |
| `~/.local/share/skillshare/backups/` | Backup directory |
### Environment Variables
+2 -2
View File
@@ -127,7 +127,7 @@ Run `skillshare doctor` to see current trash status (item count, size, age).
| | backup | trash |
|---|---|---|
| **Protects** | target directories (sync snapshots) | source skills (uninstall) |
| **Location** | `~/.config/skillshare/backups/` | `~/.config/skillshare/trash/` |
| **Location** | `~/.local/share/skillshare/backups/` | `~/.local/share/skillshare/trash/` |
| **Triggered by** | `sync`, `target remove` | `uninstall` |
| **Restore with** | `skillshare restore <target>` | `skillshare trash restore <name>` |
| **Auto-cleanup** | manual (`backup --cleanup`) | 7 days |
@@ -255,7 +255,7 @@ Thousands of small skills work fine.
### Where are backups stored?
```
~/.config/skillshare/backups/<timestamp>/
~/.local/share/skillshare/backups/<timestamp>/
```
### How long are backups kept?
+9 -9
View File
@@ -11,14 +11,14 @@ Protect your skills and recover from mistakes.
Skillshare maintains automatic backups and provides manual backup/restore commands.
```
┌─────────────────────────────────────────────────────────────┐
│ BACKUP SYSTEM │
│ │
│ TARGETS ──► backup ──► ~/.config/skillshare/backups/ │
│ │
│ BACKUPS ──► restore ──► TARGETS │
│ │
└─────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ BACKUP SYSTEM │
│ │
│ TARGETS ──► backup ──► ~/.local/share/skillshare/backups/ │
│ │
│ BACKUPS ──► restore ──► TARGETS │
│ │
└───────────────────────────────────────────────────────────────┘
```
---
@@ -30,7 +30,7 @@ Backups are created automatically before:
- `skillshare sync`
- `skillshare target remove`
**Location:** `~/.config/skillshare/backups/<timestamp>/`
**Location:** `~/.local/share/skillshare/backups/<timestamp>/`
---