Git cleanup
Contract
| Field |
Bound contract |
| Trigger |
The user explicitly invokes branch/worktree cleanup for a repository with accumulated local branches or worktrees. |
| Authority |
Restrict changes to VCS-tracked local branches and clean worktrees; show the exact set before any deletion; use git reflog and remote refs as recovery. |
| Side effect |
Delete confirmed local git branches and clean worktrees only; dirty worktrees and protected branches are refused. |
| Done |
Every local branch is categorized or surfaced as unanalyzed, every recommended deletion has evidence, exact quoted commands receive final confirmation, and each command is reported as deleted or failed. |
Inputs
A local git repository path (defaults to the current working directory). No remote credentials, no force-push targets, no protected-branch list beyond the repository's own configuration. The user supplies final confirmation for each deletion command; nothing is deleted without it.
Procedure
- Run
git branch -vv and git worktree list to enumerate every local branch and worktree. Record the current branch and the default upstream branch as protected; never propose their deletion. Done when: every local branch and worktree is enumerated and the current branch plus default upstream are marked protected.
- For each local branch, determine merge status against its upstream and against the current branch: run
git branch --merged and git branch --no-merged, then git log <branch> --not <upstream> --oneline to surface unmerged commits. Categorize each branch as merged, unmerged-with-evidence, or unanalyzed when the upstream is missing or the comparison is ambiguous. Done when: each branch carries one of merged, unmerged-with-evidence, or unanalyzed with its evidence.
- For each worktree, run
git -C <path> status --porcelain to classify it as clean or dirty. Mark dirty worktrees as refused for deletion. Done when: every worktree is classified clean or dirty.
- For every branch or clean worktree recommended for deletion, attach the evidence that justifies it: the merge commit SHA, the empty
git log output proving no unique commits, or the worktree's clean status. Branches categorized unanalyzed are surfaced with their reason and never recommended for deletion. Done when: each recommended deletion has its evidence attached and no unanalyzed branch is recommended.
- Present the full categorized list and, for each recommended deletion, the exact quoted command the user must confirm (for example
git branch -d <name> or git worktree remove <path>). Do not execute any command yet. Done when: the categorized list and every recommended deletion's exact quoted command are shown, with nothing executed.
- Wait for explicit human confirmation of each exact quoted command. Refuse to batch, abbreviate, or infer confirmation. Done when: the user confirms each exact quoted command individually, or declines.
- Execute only the confirmed commands, one at a time, in the order confirmed. After each command, record whether it succeeded (
deleted) or failed, capturing the exact git error message. Done when: each confirmed command ran and is recorded deleted or failed with its git error message.
Failure and recovery
Dirty worktree: refuse deletion, report the uncommitted changes, and stop. The user must commit, stash, or discard changes before retrying.Protected branch: refuse deletion, name the branch, and stop. Protected branches are the current branch, the default upstream, and any branch the repository marks protected.Unanalyzed branch: surface the branch with its reason (missing upstream, ambiguous merge comparison) and never delete it. Deletion requires the user to resolve the ambiguity and re-invoke.Command failure: record the exact git error, leave all other confirmed commands pending, and report the failure. Do not retry automatically or widen scope.Missing confirmation: stop before execution. No deletion occurs. Partial results are the categorized analysis only; no branch or worktree is removed without per-command confirmation.- Recovery for an accidental deletion is
git reflog and git branch <name> <sha> for branches, or re-adding a worktree with git worktree add; state this recovery path when reporting any deletion.
Output
A categorized report of every local branch (merged, unmerged-with-evidence, unanalyzed, or protected) and every worktree (clean, dirty, or protected), each recommended deletion with its evidence and exact quoted command, the set of confirmed commands, and a per-command result of deleted or failed with the git error message. Branches or worktrees never confirmed remain listed as not deleted.
1---2name: git-cleanup3description: Use when the user explicitly invokes branch or worktree cleanup for a repo with accumulated local branches. Also handles tidy's scratch-file cleanup when the user says tidy and the target is scratch artifacts. Don't use for remote branch deletion or force-push operations.4---5
6# Git cleanup
7
8## Contract
9
10| Field | Bound contract |
11|---|---|
12| Trigger | The user explicitly invokes branch/worktree cleanup for a repository with accumulated local branches or worktrees. |
13| Authority | Restrict changes to VCS-tracked local branches and clean worktrees; show the exact set before any deletion; use git reflog and remote refs as recovery. |
14| Side effect | Delete confirmed local git branches and clean worktrees only; dirty worktrees and protected branches are refused. |
15| Done | Every local branch is categorized or surfaced as unanalyzed, every recommended deletion has evidence, exact quoted commands receive final confirmation, and each command is reported as deleted or failed. |
16
17## Inputs
18
19A local git repository path (defaults to the current working directory). No remote credentials, no force-push targets, no protected-branch list beyond the repository's own configuration. The user supplies final confirmation for each deletion command; nothing is deleted without it.
20
21## Procedure
22
231. Run `git branch -vv` and `git worktree list` to enumerate every local branch and worktree. Record the current branch and the default upstream branch as protected; never propose their deletion. Done when: every local branch and worktree is enumerated and the current branch plus default upstream are marked protected.
242. For each local branch, determine merge status against its upstream and against the current branch: run `git branch --merged` and `git branch --no-merged`, then `git log <branch> --not <upstream> --oneline` to surface unmerged commits. Categorize each branch as `merged`, `unmerged-with-evidence`, or `unanalyzed` when the upstream is missing or the comparison is ambiguous. Done when: each branch carries one of `merged`, `unmerged-with-evidence`, or `unanalyzed` with its evidence.
253. For each worktree, run `git -C <path> status --porcelain` to classify it as `clean` or `dirty`. Mark dirty worktrees as refused for deletion. Done when: every worktree is classified `clean` or `dirty`.
264. For every branch or clean worktree recommended for deletion, attach the evidence that justifies it: the merge commit SHA, the empty `git log` output proving no unique commits, or the worktree's clean status. Branches categorized `unanalyzed` are surfaced with their reason and never recommended for deletion. Done when: each recommended deletion has its evidence attached and no `unanalyzed` branch is recommended.
275. Present the full categorized list and, for each recommended deletion, the exact quoted command the user must confirm (for example `git branch -d <name>` or `git worktree remove <path>`). Do not execute any command yet. Done when: the categorized list and every recommended deletion's exact quoted command are shown, with nothing executed.
286. Wait for explicit human confirmation of each exact quoted command. Refuse to batch, abbreviate, or infer confirmation. Done when: the user confirms each exact quoted command individually, or declines.
297. Execute only the confirmed commands, one at a time, in the order confirmed. After each command, record whether it succeeded (`deleted`) or failed, capturing the exact git error message. Done when: each confirmed command ran and is recorded `deleted` or `failed` with its git error message.
30## Failure and recovery
31- `Dirty worktree`: refuse deletion, report the uncommitted changes, and stop. The user must commit, stash, or discard changes before retrying.
32- `Protected branch`: refuse deletion, name the branch, and stop. Protected branches are the current branch, the default upstream, and any branch the repository marks protected.
33- `Unanalyzed branch`: surface the branch with its reason (missing upstream, ambiguous merge comparison) and never delete it. Deletion requires the user to resolve the ambiguity and re-invoke.
34- `Command failure`: record the exact git error, leave all other confirmed commands pending, and report the failure. Do not retry automatically or widen scope.
35- `Missing confirmation`: stop before execution. No deletion occurs. Partial results are the categorized analysis only; no branch or worktree is removed without per-command confirmation.
36- Recovery for an accidental deletion is `git reflog` and `git branch <name> <sha>` for branches, or re-adding a worktree with `git worktree add`; state this recovery path when reporting any deletion.
37
38## Output
39A categorized report of every local branch (`merged`, `unmerged-with-evidence`, `unanalyzed`, or `protected`) and every worktree (`clean`, `dirty`, or `protected`), each recommended deletion with its evidence and exact quoted command, the set of confirmed commands, and a per-command result of `deleted` or `failed` with the git error message. Branches or worktrees never confirmed remain listed as not deleted.
majiayu000