--- name: tidy-git description: Mechanical git repo hygiene. Prunes stale remote-tracking refs, deletes merged local branches (with confirmation), and reports stashes, untracked files, and unpushed work. Never touches remote state. Safe by default — destructive operations require explicit operator approval. model: opus --- # Tidy-Git - Mechanical Repo Hygiene Cleans up local git state that accumulates over time: remote-tracking refs for branches that no longer exist upstream, local branches that have already been merged, stale worktree references. Surfaces (without acting on) other state worth knowing about: stashes, untracked files, branches with no upstream, branches ahead of upstream, local-only tags. **Scope of action:** local repo only. The skill never pushes, never force-pushes, never deletes anything on the remote. It also never deletes unmerged work, never deletes the current branch, never deletes the main branch. **Reversibility note:** branches deleted by this skill can be recovered from `git reflog` for ~90 days. Tags and stashes are not deleted by this skill (the user makes those calls). ## Philosophy **Tidy, not review.** The user invoked `/tidy-git` because they want cleanup, not analysis. The skill defaults to *doing* the safe operations rather than presenting findings for approval. Operator approval is required only for the borderline-safe operations (merged-branch deletion) where a preview is genuinely useful. **Find→fix seam stays small.** This skill exists in the `/tidy-*` namespace because the seam between "detect a stale ref" and "delete it" is essentially zero. Adding a review-and-approve step for every mechanical operation would turn a 5-second cleanup into a 5-minute interactive session. **Boundary respected: local only.** Repo hygiene that touches the remote (e.g., deleting remote branches, force-pushing to clean up history) is out of scope. Those operations have non-local effects and warrant explicit per-action operator decisions, not bundled into a "tidy" workflow. ## Workflow Overview ``` ┌──────────────────────────────────────────────────────┐ │ TIDY-GIT │ ├──────────────────────────────────────────────────────┤ │ 1. Detect repo context (main branch, current │ │ branch, remote) │ │ 2. Run zero-risk auto-operations │ │ ├─ Prune remote-tracking refs │ │ └─ Prune stale worktree refs │ │ 3. Inventory borderline-safe operations │ │ └─ Merged local branches (excluding main + │ │ current) │ │ 4. Inventory informational state │ │ ├─ Stashes (with age) │ │ ├─ Branches with no upstream │ │ ├─ Branches ahead of upstream │ │ ├─ Local-only tags │ │ └─ Untracked files │ │ 5. Present preview + confirm for branch deletion │ │ 6. Execute approved deletions │ │ 7. Final summary │ └──────────────────────────────────────────────────────┘ ``` ## Workflow Details ### 1. Detect Repo Context Run the following checks before any cleanup: - **Is this a git repo?** `git rev-parse --is-inside-work-tree`. If not, abort cleanly. - **What is the main branch?** Try in order: `git symbolic-ref refs/remotes/origin/HEAD` (the canonical answer if `origin/HEAD` is set), then check for `main`, then `master`. If none detected, ask the user. - **What is the current branch?** `git branch --show-current`. Note for safety checks. - **Is the working tree clean?** Not a blocker, but worth noting in the summary — it's informational state. Record the main branch and current branch for safety checks in later steps. These two branches are never deleted by this skill. ### 2. Run Zero-Risk Auto-Operations These operations remove only *references* — they never delete commits, objects, or files. Run without operator confirmation; they cannot lose work. **2a. Prune remote-tracking refs.** ``` git remote prune origin ``` Removes local refs under `refs/remotes/origin/` for branches that no longer exist on the remote. Record the count removed. If the project has multiple remotes, prune each one in turn. **2b. Prune stale worktree refs.** ``` git worktree prune ``` Removes references to worktrees whose directories have already been deleted from disk. Does not touch worktrees that still exist. Record the count removed. ### 3. Inventory Borderline-Safe Operations #### Merged local branches Identify local branches that have been fully merged into the main branch: ``` git branch --merged ``` **Exclude from the list:** - The main branch itself - The current branch (`git branch --show-current`) - Any branch passed as a `--keep` argument by the user (future extension) For each remaining branch, also record: - Last commit SHA (so the user can recover via reflog if they regret the delete) - Last commit date and message (for the preview) - Whether the branch has an upstream (informational) **Caveat to surface in the preview:** `git branch --merged` only detects branches whose tip commit is reachable from the main branch. Branches that were merged via *squash-merge* or *rebase-merge* will NOT show up here — their tip commit is different from anything on main. Those branches will surface in step 4's "branches ahead of upstream" category, where the user can decide. ### 4. Inventory Informational State These are reported but never modified by the skill. **4a. Stashes.** `git stash list --date=relative`. Record count and the list. Stashes are never deleted by this skill — the user decides if they want to drop or apply. **4b. Branches with no upstream.** `git for-each-ref --format='%(refname:short) %(upstream)' refs/heads/` and filter for empty upstream. These are local branches that have never been pushed (or whose upstream was deleted without removing the local branch). Surface as informational — they might be intentional local-only work or forgotten branches. **4c. Branches ahead of upstream.** For each branch with an upstream, check `git rev-list --count @{u}..`. If non-zero, the branch has commits not on the remote. Report each with the count of commits ahead. Useful for spotting forgotten pushes. **4d. Local-only tags.** Compare `git tag` against `git ls-remote --tags origin` (or the configured remote). Tags present locally but not remotely are local-only. These may be intentional backups (e.g., `pre-rebase-backup-*`) and are reported without action. Surface them so the operator can review and drop manually if desired. **4e. Untracked files.** `git status --porcelain` and filter for untracked. Report count and a representative sample (cap at 10 names; collapse the rest). Not deleted by this skill — `/pre-compact` handles session-trash cleanup with judgment; this skill stays out of that lane. ### 5. Present Preview + Confirm If step 3 found merged branches eligible for deletion, present them and ask for confirmation: ``` ## Branch deletion preview The following local branches are fully merged into
and are safe to delete. Their SHAs are preserved in git reflog for ~90 days if you need to recover. feat/old-feature (last commit: 2026-04-15, sha 4a3b2c1) fix/typo-readme (last commit: 2026-04-22, sha 9f8e7d6) feat/old-experiment (last commit: 2026-03-08, sha 1a2b3c4) Delete all? Select specific? Keep all? ``` Use `AskUserQuestion`. Default to "delete all" since the operator invoked the skill expecting cleanup. **Three responses:** - **Delete all** — proceed to step 6 with the full list. - **Select specific** — operator picks a subset; proceed to step 6 with the selection. - **Keep all** — skip step 6 and proceed to the summary. **If step 3 found no merged branches:** skip directly to the summary. No preview needed. ### 6. Execute Approved Deletions For each approved branch: ``` git branch -d ``` Use the **lowercase `-d`** (safe delete) — it refuses to delete a branch that isn't actually merged. This guards against rare cases where step 3's `--merged` check returns a false positive (e.g., a branch was merged-then-reset locally). If `-d` fails, surface the error and skip that branch; do **not** fall back to `-D`. Record each successful deletion (branch name + SHA) for the summary. ### 7. Final Summary ``` ## Tidy-Git Complete ### Cleaned - Pruned N stale remote-tracking refs (origin) - Pruned M stale worktree refs - Deleted K merged local branches: - feat/old-feature (sha 4a3b2c1) - fix/typo-readme (sha 9f8e7d6) ### Recoverable - Deleted branches are in git reflog for ~90 days: `git reflog | grep ` then `git branch ` ### Worth Reviewing (no action taken) - Stashes: N (oldest from 2026-02-12) `git stash list` to inspect; `git stash drop ` to delete - Local-only branches with no upstream: M feat/wip-thing, fix/local-experiment - Branches ahead of upstream: K feat/almost-done (3 commits ahead of origin/feat/almost-done) - Local-only tags: J pre-rebase-backup-2026-05-11 - Untracked files: I (sample below; see `git status` for full list) /tmp/scratch.txt, PROJECT_PROGRESS.md, debug.log ``` If any of the auto-operations failed (e.g., `git remote prune` errored because there's no remote configured), report the failure inline and continue with the rest of the workflow. ## Safety Invariants The skill must never: - Delete the main branch. - Delete the current branch. - Use `git branch -D` (force delete) on any branch, ever. If `-d` fails, the branch stays. - Run `git push`, `git push --force`, `git push --delete`, or any other operation that affects the remote. - Run `git stash drop`, `git stash clear`, or otherwise discard stashes. - Run `git tag -d` on any tag. (Local-only tags are reported, not deleted.) - Run `git clean` to remove untracked files. (Untracked files are reported, not deleted; `/pre-compact` handles session-trash with judgment.) - Run `git gc`, `git gc --aggressive`, or `git prune` on the object database. Git's `gc --auto` runs when needed. These invariants are categorical. The skill does not offer flags or options to override them — if the user wants any of these operations, they invoke `git` directly. ## Abort Conditions **Abort the workflow:** - Not in a git repository. - Repository is mid-operation (mid-rebase, mid-merge, mid-cherry-pick) — surface this and stop. The user should resolve the in-progress operation first. - User interrupts. **Do NOT abort for:** - No remote configured (skip the prune step, continue). - No worktrees (skip the worktree prune step, continue). - Empty inventory (every category empty is a valid outcome — report "nothing to clean" and exit). - Individual `git branch -d` failures (skip the branch, continue with the rest). ## Example Session ``` > /tidy-git Detected: main branch = "master", current = "feat/wip-thing" Pruning remote-tracking refs... 4 removed (feat/old-1, feat/old-2, feat/old-3, fix/merged-pr). Pruning worktree refs... 0 removed. Inventory: - Merged local branches: 3 (eligible for deletion) - Stashes: 2 (oldest from 2026-02-12, message: "wip: trying caching") - Branches with no upstream: 1 (feat/wip-thing) - Branches ahead of upstream: 0 - Local-only tags: 1 (pre-rebase-backup-2026-05-11) - Untracked files: 7 (incl. /tmp/scratch.txt, PROJECT_PROGRESS.md) ## Branch deletion preview The following local branches are fully merged into master and safe to delete. SHAs preserved in git reflog for ~90 days. feat/old-feature (2026-04-15, sha 4a3b2c1) fix/typo-readme (2026-04-22, sha 9f8e7d6) feat/old-experiment (2026-03-08, sha 1a2b3c4) Delete all? > Yes Deleting feat/old-feature... done (sha 4a3b2c1). Deleting fix/typo-readme... done (sha 9f8e7d6). Deleting feat/old-experiment... done (sha 1a2b3c4). ## Tidy-Git Complete ### Cleaned - Pruned 4 stale remote-tracking refs (origin) - Deleted 3 merged local branches ### Recoverable - `git reflog | grep ` then `git branch ` ### Worth Reviewing (no action taken) - Stashes: 2 (oldest from 2026-02-12) `git stash list` to inspect; `git stash drop ` to delete - Local-only branches with no upstream: 1 (feat/wip-thing) - Local-only tags: 1 (pre-rebase-backup-2026-05-11) - Untracked files: 7 /tmp/scratch.txt, PROJECT_PROGRESS.md, debug.log, ... (4 more) Run `git status` for the full list. ```