From d1a0cb0a2edd4cec39ff261d5f540c6cfd6a339d Mon Sep 17 00:00:00 2001 From: Mattt Zmuda Date: Mon, 16 Nov 2026 04:00:51 -0800 Subject: [PATCH 1/5] Make the SwiftPM pin check optional for DerivedData folders --- internal/scan/swiftpm.go | 77 ++++++++++++++++++++++++++++++---------- 1 file changed, 59 insertions(+), 18 deletions(-) diff --git a/internal/scan/swiftpm.go b/internal/scan/swiftpm.go index 3d51864..881f3f4 100644 --- a/internal/scan/swiftpm.go +++ b/internal/scan/swiftpm.go @@ -17,8 +17,10 @@ import ( // and a bare clone in repositories/; "swift package resolve" // and "xcodebuild -resolvePackageDependencies" make both again. type packageLayout struct { - dir string // the directory that holds checkouts and repositories - resolved string // the Package.resolved file beside Package.swift + dir string // the directory that holds checkouts and repositories + // resolved is the Package.resolved file beside Package.swift, + // or "" when there is no pin file to check the clones against. + resolved string } // swiftPMLayout returns the layout of c when c is a SwiftPM cache: @@ -70,10 +72,18 @@ type managedRepo struct { // except for the repositories that SwiftPM manages in a SwiftPM cache, // which checkManaged then checks with Git. func guardCache(ctx context.Context, c Candidate, measure bool) (int64, string) { - layout := swiftPMLayout(c) - size, reason, repos := walkCache(c.Path, measure, true, layout) + return guardTree(ctx, c.Path, swiftPMLayout(c), measure) +} + +// guardTree measures dir, with measure, and returns why dir must not be deleted, +// or "" when it may be. +// It refuses a Git repository at any depth, as walkCache does, +// except for the repositories that layout lets through, +// which checkManaged then checks with Git. The size of a refused dir is 0. +func guardTree(ctx context.Context, dir string, layout *packageLayout, measure bool) (int64, string) { + size, reason, repos := walkCache(dir, measure, true, layout) if reason == "" && len(repos) > 0 { - reason = checkManaged(ctx, c.Path, layout, repos) + reason = checkManaged(ctx, dir, layout, repos) } if reason != "" { size = 0 @@ -81,6 +91,27 @@ func guardCache(ctx context.Context, c Candidate, measure bool) (int64, string) return size, reason } +// GuardDerivedData measures each folder in dirs, with measure, +// and returns at the same index why the folder must not be deleted, or "". +// Each folder is one that Xcode keeps for a workspace in +// ~/Library/Developer/Xcode/DerivedData, and the caller has found +// that its workspace no longer exists, so there is no Package.resolved +// to check its SwiftPM clones against. +// It refuses a Git repository at any depth and a directory that it cannot read, +// as walkCache describes, except for the clones that Xcode's SwiftPM keeps +// in SourcePackages, which it checks as checkManaged describes, +// without the pin checks. +// The size of a refused folder is 0. +func GuardDerivedData(ctx context.Context, dirs []string, measure bool) ([]int64, []string) { + sizes := make([]int64, len(dirs)) + reasons := make([]string, len(dirs)) + parallel(len(dirs), func(i int) { + layout := &packageLayout{dir: filepath.Join(dirs[i], "SourcePackages")} + sizes[i], reasons[i] = guardTree(ctx, dirs[i], layout, measure) + }) + return sizes, reasons +} + // pin is what Package.resolved records for one package. type pin struct { location string // the URL or path that SwiftPM clones @@ -98,14 +129,18 @@ type mirror struct { // It checks the bare clones first, as checkMirror describes, // because a checkout trusts only the tags that its bare clone also holds, // then each checkout, as checkCheckout describes. +// When the layout has no Package.resolved, it skips the checks against pins. func checkManaged(ctx context.Context, dir string, layout *packageLayout, repos []managedRepo) string { - pins, err := readPins(layout.resolved) - if err != nil { - what := "a Git repository" - if repos[0].bare { - what = "a Git directory" + var pins map[string]pin + if layout.resolved != "" { + var err error + if pins, err = readPins(layout.resolved); err != nil { + what := "a Git repository" + if repos[0].bare { + what = "a Git directory" + } + return repoReason(dir, repos[0].path, what) + ", and Package.resolved cannot be read: " + err.Error() } - return repoReason(dir, repos[0].path, what) + ", and Package.resolved cannot be read: " + err.Error() } var mirrors []mirror for _, r := range repos { @@ -122,7 +157,7 @@ func checkManaged(ctx context.Context, dir string, layout *packageLayout, repos if r.bare { continue } - if why := checkCheckout(ctx, r.path, pins[filepath.Base(r.path)].revision, mirrors); why != "" { + if why := checkCheckout(ctx, r.path, pins, mirrors); why != "" { return repoReason(dir, r.path, "a Git repository") + " " + why } } @@ -132,7 +167,8 @@ func checkManaged(ctx context.Context, dir string, layout *packageLayout, repos // checkMirror returns the bare clone at gitDir, or why it is not one // that SwiftPM can make again. // It must be bare, have no linked worktrees, and have one remote, origin, -// set up as a mirror of a location that a pin in Package.resolved names. +// set up as a mirror of a location that a pin in Package.resolved names, +// unless pins is nil, which skips that check. // No commit may be held only by its reflogs. // Every ref in such a mirror came from a fetch or a push, // and a push leaves no record in a bare repository, @@ -166,7 +202,7 @@ func checkMirror(ctx context.Context, gitDir string, pins map[string]pin) (mirro if err != nil { return fail(err) } - if !pinned(url, pins) { + if pins != nil && !pinned(url, pins) { return mirror{}, "whose origin no pin in Package.resolved names" } out, _, err = g("rev-list", "-n", "1", "--reflog", "--not", "--all") @@ -287,13 +323,14 @@ func sameLocation(url, location string) bool { // checkCheckout returns why the checkout at dir has work that // "swift package resolve" would not restore, or "". -// revision is the one that Package.resolved pins for it, or "" when none does. +// Its HEAD must be the revision that pins holds for its identity, +// the name of dir, unless pins is nil, which skips that check. // Its one remote, origin, must be one of mirrors. // A commit counts as one that SwiftPM can restore only when HEAD, // a ref in refs/remotes/origin, or a tag with the same object in the mirror // holds it. A tag that only the checkout has, a local branch, or a reflog // does not count, and a push from the checkout to the mirror refuses it. -func checkCheckout(ctx context.Context, dir, revision string, mirrors []mirror) string { +func checkCheckout(ctx context.Context, dir string, pins map[string]pin, mirrors []mirror) string { gitDir := filepath.Join(dir, ".git") if why := worktreesReason(gitDir); why != "" { return why @@ -316,8 +353,11 @@ func checkCheckout(ctx context.Context, dir, revision string, mirrors []mirror) if err != nil { return fail(err) } - if revision == "" || strings.TrimSpace(string(out)) != strings.ToLower(revision) { - return "whose HEAD is not a commit that Package.resolved pins for it" + if pins != nil { + revision := pins[filepath.Base(dir)].revision + if revision == "" || strings.TrimSpace(string(out)) != strings.ToLower(revision) { + return "whose HEAD is not a commit that Package.resolved pins for it" + } } // Set every option that would hide a change, in case configuration changes it. @@ -409,6 +449,7 @@ func worktreesReason(gitDir string) string { // readPins returns what a Package.resolved file pins for each package identity. // It reads versions 2 and 3, which key pins by identity. +// The map is never nil, so that checkMirror and checkCheckout check against it. func readPins(path string) (map[string]pin, error) { data, err := os.ReadFile(path) if err != nil { From e809e4530ef9c089b8a8a7c2b891db87a623f78b Mon Sep 17 00:00:00 2001 From: Mattt Zmuda Date: Mon, 16 Nov 2026 04:00:52 -0800 Subject: [PATCH 2/5] Refuse stale DerivedData folders that hold work Git cannot restore --- internal/global/global.go | 6 +- internal/global/xcode.go | 34 ++++++-- internal/global/xcode_test.go | 153 +++++++++++++++++++++++++++++++++ internal/report/report.go | 6 +- internal/report/report_test.go | 38 ++++++++ 5 files changed, 229 insertions(+), 8 deletions(-) diff --git a/internal/global/global.go b/internal/global/global.go index 1c2bfce..a29aed4 100644 --- a/internal/global/global.go +++ b/internal/global/global.go @@ -44,6 +44,10 @@ type Entry struct { // It is false for a clear rule, for a rule whose targets give Bytes, // and for the Xcode rule, whose Bytes is the size of the folders that it deletes. WholeCache bool `json:"whole_cache,omitempty"` + // RefusedFolders are the folders that the rule would remove + // but keeps because they are or hold a Git repository, with the reason. + // They are not in Bytes or Command. Only the Xcode rule sets them. + RefusedFolders []scan.Refusal `json:"refused_folders,omitempty"` argv []string guards []*guard @@ -298,7 +302,7 @@ func (r Runner) List(ctx context.Context, rs []rules.Global) []Entry { e := &entries[i] e.WholeCache = e.Skipped == "" && e.Kind == rules.KindPrune && !e.targeted } - if e, ok := r.xcodeEntry(); ok { + if e, ok := r.xcodeEntry(ctx); ok { entries = append(entries, e) } return entries diff --git a/internal/global/xcode.go b/internal/global/xcode.go index 1f28aa5..746ccda 100644 --- a/internal/global/xcode.go +++ b/internal/global/xcode.go @@ -8,6 +8,7 @@ import ( "io/fs" "os" "path/filepath" + "slices" "strings" "github.com/mattt/plonge/internal/clean" @@ -18,10 +19,13 @@ import ( // Xcode has no prune command, so this one rule is built in. // A folder in DerivedData is stale when its info.plist names a WorkspacePath // that no longer exists. Plonge keeps every other folder. +// It also refuses a stale folder that holds a Git repository +// with work that Git cannot restore, as scan.GuardDerivedData describes, +// and reports it in the entry's RefusedFolders. // xcodeEntry returns the rule for stale DerivedData folders, // or false when it does not apply on this machine. -func (r Runner) xcodeEntry() (Entry, bool) { +func (r Runner) xcodeEntry(ctx context.Context) (Entry, bool) { if r.GOOS != "darwin" { return Entry{}, false } @@ -31,13 +35,20 @@ func (r Runner) xcodeEntry() (Entry, bool) { return Entry{}, false } e := Entry{ID: rules.XcodeRuleID, Tool: "xcode", Kind: rules.KindPrune, Path: dir, stale: []string{}} + var stale []string for _, ent := range ents { if folder := filepath.Join(dir, ent.Name()); ent.IsDir() && staleFolder(folder) { - e.stale = append(e.stale, folder) + stale = append(stale, folder) } } - for _, n := range scan.Sizes(e.stale) { - e.Bytes += n + sizes, reasons := scan.GuardDerivedData(ctx, stale, true) + for i, folder := range stale { + if reasons[i] != "" { + e.refuseFolder(folder, reasons[i]) + continue + } + e.stale = append(e.stale, folder) + e.Bytes += sizes[i] } e.Command = fmt.Sprintf("delete %d stale DerivedData directories (built in)", len(e.stale)) return e, true @@ -90,14 +101,27 @@ func workspacePath(plist string) (string, bool) { return "", false } +// refuseFolder records a stale folder that plonge must not delete. +func (e *Entry) refuseFolder(folder, reason string) { + e.RefusedFolders = append(e.RefusedFolders, scan.Refusal{Path: folder, Rule: e.ID, Reason: reason}) +} + // applyXcode deletes the stale folders, checking each one again first. -func applyXcode(_ context.Context, o *Outcome) { +// A folder that now holds a Git repository with work that Git cannot restore +// is refused and kept, and the other folders are still deleted. +func applyXcode(ctx context.Context, o *Outcome) { + // The outcome shares its slices with the listed entry; do not write to them. + o.RefusedFolders = slices.Clone(o.RefusedFolders) var failures []string for _, folder := range o.stale { info, err := os.Lstat(folder) if err != nil || !info.IsDir() || !staleFolder(folder) { continue } + if _, reasons := scan.GuardDerivedData(ctx, []string{folder}, false); reasons[0] != "" { + o.refuseFolder(folder, reasons[0]) + continue + } before := scan.DiskUsage(folder) if err := clean.RemoveTree(folder); err != nil { failures = append(failures, err.Error()) diff --git a/internal/global/xcode_test.go b/internal/global/xcode_test.go index 6c37114..92396e1 100644 --- a/internal/global/xcode_test.go +++ b/internal/global/xcode_test.go @@ -4,6 +4,7 @@ import ( "context" "fmt" "os" + "os/exec" "path/filepath" "strings" "testing" @@ -126,3 +127,155 @@ func TestXcodeOnlyOnDarwinWithTheDirectory(t *testing.T) { t.Errorf("linux: %+v", got) } } + +// staleWithClones makes a stale DerivedData folder in root whose +// SourcePackages hold a bare mirror of a dependency and a checkout of it, +// laid out as Xcode's SwiftPM lays them out. The checkout is detached +// at the dependency's first commit, which no Package.resolved pins, +// because the workspace that held the pins is gone. +// It returns the folder and the checkout. +func staleWithClones(t *testing.T, home, root, name string) (folder, checkout string) { + t.Helper() + gone := filepath.Join(home, name+".xcworkspace") + folder = derivedFolder(t, root, name+"-abc", fmt.Sprintf(plistFormat, gone)) + upstream := filepath.Join(t.TempDir(), "dep") + commitRepo(t, upstream) + first := strings.TrimSpace(gitOutput(t, upstream, "rev-parse", "HEAD")) + addFile(t, filepath.Join(upstream, "more")) + gitRun(t, upstream, "add", ".") + gitRun(t, upstream, "-c", "user.name=T", "-c", "user.email=t@example.com", "commit", "-q", "-m", "two") + + packages := filepath.Join(folder, "SourcePackages") + mirror := filepath.Join(packages, "repositories", "dep-95d00fdd") + checkout = filepath.Join(packages, "checkouts", "dep") + for _, dir := range []string{filepath.Dir(mirror), filepath.Dir(checkout)} { + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + } + gitRun(t, packages, "clone", "-q", "--mirror", upstream, mirror) + gitRun(t, packages, "clone", "-q", "--shared", "--no-checkout", mirror, checkout) + gitRun(t, checkout, "checkout", "-q", "--detach", first) + return folder, checkout +} + +func gitOutput(t *testing.T, dir string, args ...string) string { + t.Helper() + cmd := exec.Command("git", args...) + cmd.Dir = dir + out, err := cmd.Output() + if err != nil { + t.Fatalf("git %v: %v", args, err) + } + return string(out) +} + +// TestXcodeRefusesFoldersWithWork lists stale folders whose Git repositories +// hold work that Git cannot restore, keeps them, and deletes the one +// whose SwiftPM clones Xcode can make again. +func TestXcodeRefusesFoldersWithWork(t *testing.T) { + bin := t.TempDir() + withGit(t, bin) + r := Runner{Home: realTempDir(t), GOOS: "darwin"} + root := filepath.Join(r.Home, "Library", "Developer", "Xcode", "DerivedData") + + clean, _ := staleWithClones(t, r.Home, root, "Clean") + + modified, checkout := staleWithClones(t, r.Home, root, "Modified") + if err := os.WriteFile(filepath.Join(checkout, "work"), []byte("edit"), 0o644); err != nil { + t.Fatal(err) + } + + committed, checkout := staleWithClones(t, r.Home, root, "Committed") + head := strings.TrimSpace(gitOutput(t, checkout, "rev-parse", "HEAD")) + gitRun(t, checkout, "switch", "-q", "-c", "local") + addFile(t, filepath.Join(checkout, "local")) + gitRun(t, checkout, "add", ".") + gitRun(t, checkout, "-c", "user.name=T", "-c", "user.email=t@example.com", "commit", "-q", "-m", "local") + gitRun(t, checkout, "checkout", "-q", "--detach", head) + + unrelated, _ := staleWithClones(t, r.Home, root, "Unrelated") + commitRepo(t, filepath.Join(unrelated, "Build", "Intermediates.noindex", "notes")) + + unreadable := derivedFolder(t, root, "Unreadable-abc", fmt.Sprintf(plistFormat, filepath.Join(r.Home, "Unreadable.xcworkspace"))) + locked := filepath.Join(unreadable, "Build", "Locked") + if err := os.Mkdir(locked, 0o000); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(locked, 0o755) }) + if _, err := os.ReadDir(locked); err == nil { + t.Skip("a directory with mode 0 is readable, as it is for root") + } + + ctx := context.Background() + entries := r.List(ctx, nil) + if len(entries) != 1 { + t.Fatalf("entries = %+v", entries) + } + e := entries[0] + if !strings.Contains(e.Command, "delete 1 stale") || e.Bytes < 50_000 || e.Bytes > 1_000_000 { + t.Errorf("entry = %+v", e) + } + want := map[string]string{ + modified: "contains a Git repository at SourcePackages/checkouts/dep that has changed, untracked, or ignored files", + committed: "contains a Git repository at SourcePackages/checkouts/dep that has commits that only its local branches, tags, or reflogs hold", + unrelated: "contains a Git repository at Build/Intermediates.noindex/notes", + unreadable: "cannot check for Git repositories: ", + } + if len(e.RefusedFolders) != len(want) { + t.Errorf("refused = %+v", e.RefusedFolders) + } + for _, f := range e.RefusedFolders { + if w, ok := want[f.Path]; !ok || !strings.HasPrefix(f.Reason, w) || f.Rule != e.ID { + t.Errorf("refusal %+v, want reason %q", f, w) + } + } + + res := r.Clean(ctx, entries, Options{Apply: true}) + if o := res.Outcomes[0]; o.Status != Ran || len(o.RefusedFolders) != len(want) { + t.Errorf("outcome = %+v", o) + } + if _, err := os.Stat(clean); !os.IsNotExist(err) { + t.Errorf("the folder with clean clones is still there: %v", err) + } + for folder := range want { + if _, err := os.Stat(filepath.Join(folder, "Build", "blob")); err != nil { + t.Errorf("%s lost its files: %v", filepath.Base(folder), err) + } + } +} + +// TestXcodeRechecksRepositoriesBeforeDeleting adds a repository to a stale +// folder after the listing, and to the clones of another one. +func TestXcodeRechecksRepositoriesBeforeDeleting(t *testing.T) { + bin := t.TempDir() + withGit(t, bin) + r := Runner{Home: realTempDir(t), GOOS: "darwin"} + root := filepath.Join(r.Home, "Library", "Developer", "Xcode", "DerivedData") + plain := derivedFolder(t, root, "Plain-abc", fmt.Sprintf(plistFormat, filepath.Join(r.Home, "Plain.xcworkspace"))) + cloned, checkout := staleWithClones(t, r.Home, root, "Cloned") + + ctx := context.Background() + entries := r.List(ctx, nil) + if e := entries[0]; !strings.Contains(e.Command, "delete 2 stale") || len(e.RefusedFolders) != 0 { + t.Fatalf("entry = %+v", e) + } + commitRepo(t, filepath.Join(plain, "Build", "repo")) + if err := os.WriteFile(filepath.Join(checkout, "untracked"), nil, 0o644); err != nil { + t.Fatal(err) + } + + res := r.Clean(ctx, entries, Options{Apply: true}) + o := res.Outcomes[0] + if o.Status != Ran || res.FreedBytes != 0 || len(o.RefusedFolders) != 2 { + t.Errorf("outcome = %+v", o) + } + if len(entries[0].RefusedFolders) != 0 { + t.Errorf("the listed entry changed: %+v", entries[0].RefusedFolders) + } + for _, folder := range []string{plain, cloned} { + if _, err := os.Stat(filepath.Join(folder, "Build", "blob")); err != nil { + t.Errorf("%s lost its files: %v", filepath.Base(folder), err) + } + } +} diff --git a/internal/report/report.go b/internal/report/report.go index 44f9def..76c4954 100644 --- a/internal/report/report.go +++ b/internal/report/report.go @@ -196,8 +196,8 @@ func writeSources(w io.Writer, sources []scan.Source) { } } -// WriteRefusals lists the caches that plonge does not report or delete -// because they are or hold a Git repository. +// WriteRefusals lists the caches, or the folders of a global rule, +// that plonge does not report or delete because they are or hold a Git repository. func WriteRefusals(w io.Writer, refused []scan.Refusal, home string) { for _, r := range refused { fmt.Fprintf(w, "Refused %s: %s\n", Tilde(r.Path, home), r.Reason) @@ -246,6 +246,7 @@ func writeGlobal(w io.Writer, entries []global.Entry, home string) error { writeRefused(w, e) } writeTargets(w, e) + WriteRefusals(w, e.RefusedFolders, home) } _, err := fmt.Fprintf(w, "Global total: %s in %s\n", HumanBytes(total), plural(n, "rule")) return err @@ -300,6 +301,7 @@ func WriteGlobalClean(w io.Writer, r global.Result, home string) error { writeRefused(w, o.Entry) } writeTargets(w, o.Entry) + WriteRefusals(w, o.RefusedFolders, home) } fmt.Fprintln(w) if r.Failed > 0 { diff --git a/internal/report/report_test.go b/internal/report/report_test.go index 679be5a..45a0040 100644 --- a/internal/report/report_test.go +++ b/internal/report/report_test.go @@ -195,6 +195,44 @@ func TestWriteGlobalRefusedAndTargets(t *testing.T) { } } +// TestWriteGlobalRefusedFolders lists the folders that a rule keeps +// as refusals in the scan and clean output, and in JSON. +func TestWriteGlobalRefusedFolders(t *testing.T) { + e := global.Entry{ID: "xcode-derived-data", Command: "delete 0 stale DerivedData directories (built in)", + RefusedFolders: []scan.Refusal{{Path: "/home/DD/App-abc", Rule: "xcode-derived-data", Reason: "contains a Git repository at Build/x"}}} + want := "Refused ~/DD/App-abc: contains a Git repository at Build/x\n" + var buf bytes.Buffer + if err := writeGlobal(&buf, []global.Entry{e}, "/home"); err != nil { + t.Fatal(err) + } + if !strings.Contains(buf.String(), want) { + t.Errorf("scan: missing %q in:\n%s", want, buf.String()) + } + res := global.Result{Applied: true, Outcomes: []global.Outcome{{Entry: e, Status: global.Ran}}} + buf.Reset() + if err := WriteGlobalClean(&buf, res, "/home"); err != nil { + t.Fatal(err) + } + if !strings.Contains(buf.String(), want) { + t.Errorf("clean: missing %q in:\n%s", want, buf.String()) + } + buf.Reset() + if err := WriteJSON(&buf, res); err != nil { + t.Fatal(err) + } + var got struct { + Outcomes []struct { + RefusedFolders []scan.Refusal `json:"refused_folders"` + } `json:"outcomes"` + } + if err := json.Unmarshal(buf.Bytes(), &got); err != nil { + t.Fatal(err) + } + if len(got.Outcomes) != 1 || len(got.Outcomes[0].RefusedFolders) != 1 || got.Outcomes[0].RefusedFolders[0] != e.RefusedFolders[0] { + t.Errorf("JSON = %s", buf.String()) + } +} + func TestWholeCacheLabel(t *testing.T) { entries := []global.Entry{ {ID: "uv", Kind: "prune", Bytes: 3 << 30, Command: "uv cache prune", WholeCache: true}, From 7ddee4aed962ad2c2e66a7a7af21b16a68fc9201 Mon Sep 17 00:00:00 2001 From: Mattt Zmuda Date: Mon, 16 Nov 2026 04:01:11 -0800 Subject: [PATCH 3/5] Document refused DerivedData folders --- README.md | 3 ++- docs/coverage.md | 10 +++++++++- docs/rules.md | 21 +++++++++++++++++++++ 3 files changed, 32 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index aafb7c1..ca7c53f 100644 --- a/README.md +++ b/README.md @@ -176,7 +176,8 @@ the Cargo rule leaves Git checkouts alone, the Deno rules leave localStorage and REPL history alone, and the Maven rule refuses a repository with locally installed artifacts. On macOS, a prune rule for Xcode selects only build directories -whose workspace no longer exists. +whose workspace no longer exists, +and refuses one that holds a Git repository with edits or local commits. See the [rule reference](docs/rules.md#global-caches) for every global action, its path, and its checks. diff --git a/docs/coverage.md b/docs/coverage.md index 1f8969a..0cbc385 100644 --- a/docs/coverage.md +++ b/docs/coverage.md @@ -460,7 +460,7 @@ Global rules require their command to be available, except for the Xcode rule. | RubyGems | none | `rubygems-cache` | `delete_contents` of `cache` in the directory that `gem env gemdir` prints; Plonge does not run `gem cleanup`, which uninstalls old gem versions | clear; requires `clean --global --include-clear --apply` to run. Installed gems stay; only the copies of their `.gem` files are deleted. | | Homebrew | none yet | `homebrew` | `brew cleanup --prune=all` | clear; requires `clean --global --include-clear --apply` to run. Homebrew can remove old installed versions as well as cached downloads; Plonge measures only `brew --cache`. | | Swift Package Manager | `.build` | `swiftpm-macos`, `swiftpm-linux` | `swift package purge-cache`, with `--cache-path` and `--scratch-path` set to the measured cache directory | clear; requires `clean --global --include-clear --apply` to run. Each rule applies only on its system. `artifacts` and `prebuilts` remain. | -| Xcode | `DerivedData` | `xcode-derived-data` | Built-in deletion of stale directories under `~/Library/Developer/Xcode/DerivedData`; no external command | prune; macOS only, when that directory can be read. Eligible with `clean --global`; requires `--apply` to delete. | +| Xcode | `DerivedData` | `xcode-derived-data` | Built-in deletion of stale directories under `~/Library/Developer/Xcode/DerivedData`; no external command | prune; macOS only, when that directory can be read. Eligible with `clean --global`; requires `--apply` to delete. Refuses a stale directory that holds a Git repository, except unchanged SwiftPM clones in `SourcePackages`, or a directory that it cannot read. | A global rule can also set `delete_contents` in place of a cleanup command, for a cache whose tool has none. @@ -482,6 +482,14 @@ The Xcode global rule selects only directories whose XML `info.plist` names an absolute `WorkspacePath` that no longer exists. It keeps directories with missing or unreadable workspace metadata and workspaces on unmounted volumes under `/Volumes`. +It also refuses a stale directory that holds a Git repository at any depth, +or a directory that it cannot read, +except the SwiftPM clones in `SourcePackages` that pass the project checks +for `.build`, other than the checks against `Package.resolved`, +which is gone with the workspace. +Without the pins, Plonge cannot tell whether a checkout was at the commit +that the workspace resolved, or whether a bare clone mirrors the package's URL; +it can tell only that neither holds work that Git cannot restore. The project `DerivedData` rule is different: it uses the project checks, without checking Xcode workspace metadata. diff --git a/docs/rules.md b/docs/rules.md index 4a5a12d..2515ea6 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -393,6 +393,27 @@ whose XML `info.plist` names an absolute `WorkspacePath` that no longer exists. It keeps a directory without a readable `WorkspacePath`, and a directory whose workspace is on a volume that is not mounted. +A stale directory usually holds the package clones that Xcode's SwiftPM keeps +in `SourcePackages`, which Xcode makes again when the workspace resolves. +Plonge allows them under the +[SwiftPM conditions](#swift-package-manager-checkouts), +except the checks against `Package.resolved`, +because the workspace that held the pins is gone: +a bare clone directly in `SourcePackages/repositories` +can mirror any origin, +and a checkout directly in `SourcePackages/checkouts` +can be at any commit that its bare clone holds. +Plonge refuses a stale directory that holds any other Git repository, +a clone that fails the other conditions, or a directory that it cannot read. +It checks again right before it deletes each directory. +The report lists each refused directory and its reason +after the rule's action, and in `refused_folders` in JSON output; +its size is not in the rule's size, and it is not counted in the action: + +```console +Refused ~/Library/Developer/Xcode/DerivedData/App-abc: contains a Git repository at SourcePackages/checkouts/dep that has changed, untracked, or ignored files +``` + You can add a rule, or replace a default with the same `id`, in `rules.toml`: From c09a30bb4a63bc32e97fc6b8e1fea4a11d8a6eb7 Mon Sep 17 00:00:00 2001 From: Mattt Zmuda Date: Mon, 16 Nov 2026 04:06:04 -0800 Subject: [PATCH 4/5] Refuse local commits at HEAD and recount after the final check --- internal/global/xcode.go | 16 +++++++-- internal/global/xcode_test.go | 68 ++++++++++++++++++++++++++++++----- internal/scan/swiftpm.go | 17 ++++++--- 3 files changed, 87 insertions(+), 14 deletions(-) diff --git a/internal/global/xcode.go b/internal/global/xcode.go index 746ccda..c509a56 100644 --- a/internal/global/xcode.go +++ b/internal/global/xcode.go @@ -50,10 +50,15 @@ func (r Runner) xcodeEntry(ctx context.Context) (Entry, bool) { e.stale = append(e.stale, folder) e.Bytes += sizes[i] } - e.Command = fmt.Sprintf("delete %d stale DerivedData directories (built in)", len(e.stale)) + e.Command = xcodeCommand(len(e.stale)) return e, true } +// xcodeCommand is the Command of the Xcode rule when it deletes n folders. +func xcodeCommand(n int) string { + return fmt.Sprintf("delete %d stale DerivedData directories (built in)", n) +} + // staleFolder reports whether a DerivedData folder's workspace is gone. // A folder without a readable WorkspacePath is not stale. func staleFolder(folder string) bool { @@ -109,11 +114,15 @@ func (e *Entry) refuseFolder(folder, reason string) { // applyXcode deletes the stale folders, checking each one again first. // A folder that now holds a Git repository with work that Git cannot restore // is refused and kept, and the other folders are still deleted. +// The outcome's size, action, and folders are rebuilt from the folders +// that pass this final check, and its size is what they held right before. func applyXcode(ctx context.Context, o *Outcome) { // The outcome shares its slices with the listed entry; do not write to them. o.RefusedFolders = slices.Clone(o.RefusedFolders) + listed := o.stale + o.stale, o.Bytes = []string{}, 0 var failures []string - for _, folder := range o.stale { + for _, folder := range listed { info, err := os.Lstat(folder) if err != nil || !info.IsDir() || !staleFolder(folder) { continue @@ -123,11 +132,14 @@ func applyXcode(ctx context.Context, o *Outcome) { continue } before := scan.DiskUsage(folder) + o.stale = append(o.stale, folder) + o.Bytes += before if err := clean.RemoveTree(folder); err != nil { failures = append(failures, err.Error()) } o.FreedBytes += max(0, before-scan.DiskUsage(folder)) } + o.Command = xcodeCommand(len(o.stale)) if len(failures) > 0 { o.Status, o.Reason = Failed, strings.Join(failures, "; ") return diff --git a/internal/global/xcode_test.go b/internal/global/xcode_test.go index 92396e1..2513069 100644 --- a/internal/global/xcode_test.go +++ b/internal/global/xcode_test.go @@ -1,13 +1,17 @@ package global import ( + "bytes" "context" + "encoding/json" "fmt" "os" "os/exec" "path/filepath" "strings" "testing" + + "github.com/mattt/plonge/internal/scan" ) const plistFormat = ` @@ -159,6 +163,18 @@ func staleWithClones(t *testing.T, home, root, name string) (folder, checkout st return folder, checkout } +// commitAtHead makes a commit in checkout and leaves HEAD at it, +// on a new local branch when attached, or detached otherwise. +func commitAtHead(t *testing.T, checkout string, attached bool) { + t.Helper() + if attached { + gitRun(t, checkout, "switch", "-q", "-c", "work") + } + addFile(t, filepath.Join(checkout, "head-work")) + gitRun(t, checkout, "add", ".") + gitRun(t, checkout, "-c", "user.name=T", "-c", "user.email=t@example.com", "commit", "-q", "-m", "work") +} + func gitOutput(t *testing.T, dir string, args ...string) string { t.Helper() cmd := exec.Command("git", args...) @@ -194,6 +210,11 @@ func TestXcodeRefusesFoldersWithWork(t *testing.T) { gitRun(t, checkout, "-c", "user.name=T", "-c", "user.email=t@example.com", "commit", "-q", "-m", "local") gitRun(t, checkout, "checkout", "-q", "--detach", head) + detached, checkout := staleWithClones(t, r.Home, root, "Detached") + commitAtHead(t, checkout, false) + attached, checkout := staleWithClones(t, r.Home, root, "Attached") + commitAtHead(t, checkout, true) + unrelated, _ := staleWithClones(t, r.Home, root, "Unrelated") commitRepo(t, filepath.Join(unrelated, "Build", "Intermediates.noindex", "notes")) @@ -218,7 +239,9 @@ func TestXcodeRefusesFoldersWithWork(t *testing.T) { } want := map[string]string{ modified: "contains a Git repository at SourcePackages/checkouts/dep that has changed, untracked, or ignored files", - committed: "contains a Git repository at SourcePackages/checkouts/dep that has commits that only its local branches, tags, or reflogs hold", + committed: "contains a Git repository at SourcePackages/checkouts/dep that has commits that only its HEAD, local branches, tags, or reflogs hold", + detached: "contains a Git repository at SourcePackages/checkouts/dep that has commits that only its HEAD, local branches, tags, or reflogs hold", + attached: "contains a Git repository at SourcePackages/checkouts/dep that has commits that only its HEAD, local branches, tags, or reflogs hold", unrelated: "contains a Git repository at Build/Intermediates.noindex/notes", unreadable: "cannot check for Git repositories: ", } @@ -243,10 +266,17 @@ func TestXcodeRefusesFoldersWithWork(t *testing.T) { t.Errorf("%s lost its files: %v", filepath.Base(folder), err) } } + for _, folder := range []string{detached, attached} { + if _, err := os.Stat(filepath.Join(folder, "SourcePackages", "checkouts", "dep", "head-work")); err != nil { + t.Errorf("%s lost its commit at HEAD: %v", filepath.Base(folder), err) + } + } } // TestXcodeRechecksRepositoriesBeforeDeleting adds a repository to a stale -// folder after the listing, and to the clones of another one. +// folder after the listing, an untracked file to the clones of another one, +// and a commit at HEAD to a third, and deletes only a fourth. +// The outcome's size and action count only the folder that it deleted. func TestXcodeRechecksRepositoriesBeforeDeleting(t *testing.T) { bin := t.TempDir() withGit(t, bin) @@ -254,28 +284,50 @@ func TestXcodeRechecksRepositoriesBeforeDeleting(t *testing.T) { root := filepath.Join(r.Home, "Library", "Developer", "Xcode", "DerivedData") plain := derivedFolder(t, root, "Plain-abc", fmt.Sprintf(plistFormat, filepath.Join(r.Home, "Plain.xcworkspace"))) cloned, checkout := staleWithClones(t, r.Home, root, "Cloned") + committed, committedCheckout := staleWithClones(t, r.Home, root, "Committed") + accepted, _ := staleWithClones(t, r.Home, root, "Accepted") ctx := context.Background() entries := r.List(ctx, nil) - if e := entries[0]; !strings.Contains(e.Command, "delete 2 stale") || len(e.RefusedFolders) != 0 { - t.Fatalf("entry = %+v", e) + listed := entries[0] + if !strings.Contains(listed.Command, "delete 4 stale") || len(listed.RefusedFolders) != 0 { + t.Fatalf("entry = %+v", listed) } commitRepo(t, filepath.Join(plain, "Build", "repo")) if err := os.WriteFile(filepath.Join(checkout, "untracked"), nil, 0o644); err != nil { t.Fatal(err) } + commitAtHead(t, committedCheckout, false) + acceptedBytes := scan.DiskUsage(accepted) res := r.Clean(ctx, entries, Options{Apply: true}) o := res.Outcomes[0] - if o.Status != Ran || res.FreedBytes != 0 || len(o.RefusedFolders) != 2 { + if o.Status != Ran || len(o.RefusedFolders) != 3 { t.Errorf("outcome = %+v", o) } - if len(entries[0].RefusedFolders) != 0 { - t.Errorf("the listed entry changed: %+v", entries[0].RefusedFolders) + if !strings.Contains(o.Command, "delete 1 stale") || o.Bytes != acceptedBytes || res.FreedBytes != acceptedBytes { + t.Errorf("outcome command %q, bytes %d, freed %d; want 1 folder of %d bytes", + o.Command, o.Bytes, res.FreedBytes, acceptedBytes) + } + var buf bytes.Buffer + if err := json.NewEncoder(&buf).Encode(o); err != nil { + t.Fatal(err) + } + if want := fmt.Sprintf(`"bytes":%d,"command":"delete 1 stale`, acceptedBytes); !strings.Contains(buf.String(), want) { + t.Errorf("JSON %s lacks %s", buf.String(), want) } - for _, folder := range []string{plain, cloned} { + if e := entries[0]; len(e.RefusedFolders) != 0 || e.Command != listed.Command || e.Bytes != listed.Bytes || len(e.stale) != 4 { + t.Errorf("the listed entry changed: %+v", e) + } + if _, err := os.Stat(accepted); !os.IsNotExist(err) { + t.Errorf("the accepted folder is still there: %v", err) + } + for _, folder := range []string{plain, cloned, committed} { if _, err := os.Stat(filepath.Join(folder, "Build", "blob")); err != nil { t.Errorf("%s lost its files: %v", filepath.Base(folder), err) } } + if _, err := os.Stat(filepath.Join(committedCheckout, "head-work")); err != nil { + t.Errorf("the commit at HEAD is gone: %v", err) + } } diff --git a/internal/scan/swiftpm.go b/internal/scan/swiftpm.go index 881f3f4..e7c6272 100644 --- a/internal/scan/swiftpm.go +++ b/internal/scan/swiftpm.go @@ -326,9 +326,10 @@ func sameLocation(url, location string) bool { // Its HEAD must be the revision that pins holds for its identity, // the name of dir, unless pins is nil, which skips that check. // Its one remote, origin, must be one of mirrors. -// A commit counts as one that SwiftPM can restore only when HEAD, -// a ref in refs/remotes/origin, or a tag with the same object in the mirror -// holds it. A tag that only the checkout has, a local branch, or a reflog +// A commit counts as one that SwiftPM can restore only when +// a ref in refs/remotes/origin, a tag with the same object in the mirror, +// or, when HEAD is at its pin, HEAD holds it. +// Without pins, HEAD itself must be a commit that those refs hold. A tag that only the checkout has, a local branch, or a reflog // does not count, and a push from the checkout to the mirror refuses it. func checkCheckout(ctx context.Context, dir string, pins map[string]pin, mirrors []mirror) string { gitDir := filepath.Join(dir, ".git") @@ -420,7 +421,12 @@ func checkCheckout(ctx context.Context, dir string, pins map[string]pin, mirrors if err != nil { return fail(err) } - args := []string{"rev-list", "-n", "1", "--all", "--reflog", "--not", "HEAD", "--glob=refs/remotes/origin/*"} + // --all includes HEAD, so without a pin a commit at HEAD that only + // the checkout holds is found, whether HEAD is detached or not. + args := []string{"rev-list", "-n", "1", "--all", "--reflog", "--not", "--glob=refs/remotes/origin/*"} + if pins != nil { + args = append(args, "HEAD") + } for name, oid := range tags { if m.tags[name] == oid { args = append(args, oid) @@ -431,6 +437,9 @@ func checkCheckout(ctx context.Context, dir string, pins map[string]pin, mirrors return fail(err) } if len(out) > 0 { + if pins == nil { + return "that has commits that only its HEAD, local branches, tags, or reflogs hold" + } return "that has commits that only its local branches, tags, or reflogs hold" } return "" From b663068d4f374472ad94a260ef12312f7b9533a5 Mon Sep 17 00:00:00 2001 From: Mattt Zmuda Date: Mon, 16 Nov 2026 04:06:04 -0800 Subject: [PATCH 5/5] Document the HEAD check and the final recount --- docs/coverage.md | 4 +++- docs/rules.md | 9 +++++++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/coverage.md b/docs/coverage.md index 0cbc385..5d041fa 100644 --- a/docs/coverage.md +++ b/docs/coverage.md @@ -489,7 +489,9 @@ for `.build`, other than the checks against `Package.resolved`, which is gone with the workspace. Without the pins, Plonge cannot tell whether a checkout was at the commit that the workspace resolved, or whether a bare clone mirrors the package's URL; -it can tell only that neither holds work that Git cannot restore. +it can tell only that neither holds work that Git cannot restore, +so a checkout's `HEAD` must be a commit that its remote-tracking refs +or its bare clone's tags hold. The project `DerivedData` rule is different: it uses the project checks, without checking Xcode workspace metadata. diff --git a/docs/rules.md b/docs/rules.md index 2515ea6..f44be71 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -402,10 +402,15 @@ because the workspace that held the pins is gone: a bare clone directly in `SourcePackages/repositories` can mirror any origin, and a checkout directly in `SourcePackages/checkouts` -can be at any commit that its bare clone holds. +can be at any commit that its `refs/remotes/origin` refs +or the tags that its bare clone also holds already hold. +A commit at the checkout's `HEAD` that no such ref holds is refused, +whether `HEAD` is detached or on a local branch. Plonge refuses a stale directory that holds any other Git repository, a clone that fails the other conditions, or a directory that it cannot read. -It checks again right before it deletes each directory. +It checks again right before it deletes each directory, +and the outcome's size and action then count only the directories +that pass that check. The report lists each refused directory and its reason after the rule's action, and in `refused_folders` in JSON output; its size is not in the rule's size, and it is not counted in the action: