Skip to content
Get Shit Done

/gsd cleanup

What It Does

Section titled “What It Does”

/gsd cleanup is a housekeeping command that removes accumulated git debris from a GSD project. It covers two categories of stale artifacts: merged GSD branches and old execution snapshot refs.

Running /gsd cleanup with no arguments handles both cases at once. Each category can also be targeted individually with a subcommand.

The command reports what it removed (or why it skipped), then exits. There is no dry-run confirmation step — cleanup is low-risk because it only removes branches that are already merged into main and snapshot refs that have been superseded by newer ones.

Usage

Section titled “Usage”
/gsd cleanup
/gsd cleanup branches
/gsd cleanup snapshots
FormWhat it does
/gsd cleanupRuns both branches and snapshots cleanup together
/gsd cleanup branchesDelete merged gsd/* branches
/gsd cleanup snapshotsPrune old refs/gsd/snapshots/ refs, keeping the 5 most recent per label

How It Works

Section titled “How It Works”

Branch Cleanup

Section titled “Branch Cleanup”

Branch cleanup runs in a straightforward sequence:

  1. List GSD branches — Finds all local branches matching gsd/*.
  2. Check for merges — Uses git branch --merged against the detected main branch to find which gsd/* branches are fully contained in main.
  3. Delete merged branches — Removes each merged branch with a standard (non-force) delete. Branches that can’t be deleted are silently skipped.
  4. Report — Shows how many were removed and how many remain.

If no gsd/* branches exist at all, or none are merged yet, the command says so and exits cleanly.

Snapshot Cleanup

Section titled “Snapshot Cleanup”

GSD uses refs/gsd/snapshots/ to store undo snapshots during task execution. These accumulate over time. Snapshot cleanup:

  1. Lists all refs under refs/gsd/snapshots/
  2. Groups them by label (the path prefix, excluding the final timestamp segment)
  3. For each label group, keeps the 5 most recent refs (sorted lexicographically, which matches chronological order given the YYYYMMDD-HHMMSS timestamp format) and deletes the rest

This means you always have at least 5 rollback points per label. Old snapshots beyond that window are pruned.

What Files It Touches

Section titled “What Files It Touches”

Reads

Section titled “Reads”
FilePurpose
git branch list (gsd/*)Identifies GSD-managed branches to check for merges
git refs (refs/gsd/snapshots/)Finds snapshot refs to prune

Deletes

Section titled “Deletes”
ArtifactCondition
git branches (gsd/*)Merged into main
git refs (refs/gsd/snapshots/<label>/<old>)Beyond the 5-per-label window for that snapshot label

Examples

Section titled “Examples”

Default cleanup — branches and snapshots together:

> /gsd cleanup


Cleaned up 3 merged branches. 1 remain.
Pruned 12 old snapshot refs. 10 remain.

No branches exist:

> /gsd cleanup branches


No GSD branches to clean up.

Branches exist but none merged yet:

> /gsd cleanup branches


4 GSD branches found, none are merged into main yet.

Branches cleaned up:

> /gsd cleanup branches


Cleaned up 2 merged branches. 1 remain.

No old snapshots to prune:

> /gsd cleanup snapshots


No snapshot refs to clean up.
Section titled “Related Commands”