git-branch-cleanup

Files (1)

• SKILL.md

SKILL.md (first lines)

# Purge stale git branches

Delete branches that are already merged. Protect every branch that still holds work.

A squash merge rewrites the commits. After a squash merge, `git branch --merged` does not
list the branch, and `git branch -d` refuses to delete it. Both tools are therefore unsafe
signals here. This skill asks GitHub what the pull request merged, then compares that commit
to the local branch tip.

## When to use

Use this skill when any of these are true:

- Merged pull requests left local branches behind.
- `git branch -vv` marks branches with `[gone]`.
- The repository has no auto-delete setting, and merged remote branches remain.
- The user names one or more branches to purge.

Do not use this skill to delete a branch with work that is not merged. Do not use it to
abandon an open pull request.

## Arguments

`$ARGUMENTS` holds an optional list of branch names.

- If the list is empty, scan the whole repository and propose candidates.
- If the list has names, evaluate only those names. Run every safety check without change. A
  named branch gets no softer treatment than a discovered one.

## Step 1: preflight

Run these commands first. Stop if the first command fails.

```bash
git rev-parse --git-dir                                   # not a repo -> stop
git symbolic-ref --quiet --short refs/remotes/origin/HEAD  # -> origin/main
git fetch --prune                                          # every later check needs this
git worktree list --porcelain                              # branches checked out elsewhere
git remote get-url origin
gh auth status
```

Find the default branch. Never assume the name `main` or `master`. If `git symbolic-ref`
gives no answer, run `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`. If
both fail, ask the user.

The `gh` result and the origin host together set the mode. GitHub origin plus valid `gh`
authentication gives full mode. Anything else gives degraded mode (see Degraded mode).

## Step 2: list the branches

```bash
git for-each-ref refs/heads \
  --format='%(refname:short)%09%(upstream:short)%09%(upstream:track)%09%(objectname:short)%09%(committerdate:relative)'
git for-each-ref refs/remotes/origin \
  --format='%(refname:short)%09%(objectname:short)%09%(committerdate:relative)'
```

`%(upstream:track)` prints `[gone]` when the remote branch no longer exists. This is the
cheapest signal for a merged-and-deleted pull request. It costs no API call.

## Step 3: find the merge state of each branch

Apply these tests in order. Stop at the first one that answers.

1. `git merge-base --is-ancestor <branch> origin/<default>` — exit 0 means a true merge or a
   fast-forward. No network needed.
2. `gh pr list --head <branch> --state all --limit 5 --json number,state,url,mergedAt,headRefOid`
   - state `MERGED` — the branch is merged. This is the squash case.
   - state `OPEN` — protect the branch. Never delete it.
   - state `CLOSED` with no `mergedAt` — the work is abandoned. See the `abandoned` bucket.
   - no pull request — go to test 3.
3. Compare the merge result to the default branch. Run this test in degraded mode, and also
   in full mode when test 2 finds no pull request.

   ```bash
   git merge-tree --write-tree origin/<default> <branch>   # prints a tree sha
   git rev-parse origin/<default>^{tree}
   ```

   Equal trees mean the branch adds nothing. The branch is merged. A non-zero exit means a
   conflict, so the branch is not merged.

   This test reads content, not history. A branch whose changes reached the default branch by
   another route also gives equal trees. The result is still safe: equal trees mean the branch
   holds no content that the default branch lacks.

Never use `git cherry` or `git branch --merged` for this test. Both compare commits, and a
squash merge rewrites the commits. Both report a fully merged branch as unmerged.
`git merge-tree` compares content, so the squash does not hide the merge.

`git merge-tree --write-tree` needs git 2.38 or later. On an older git, ask the user before
you delete anything.

## Step 4: find the commits that arrive after the merge

A squash merge makes every branch commit look absent from the default branch. Therefore
`git log origin/<default>..<branch>` cannot separate merged work from new work. Ask GitHub
for the commit that the pull request actually merged, then compare:

```bash
git cat-file -e <headRefOid>^{commit}   # the sha must exist locally
git log --oneline <headRefOid>..<branch>
git diff --stat <headRefOid>..<branch>
```

No output means the branch adds nothing new. The branch is safe to delete.
Output means the branch holds work that the pull request never took. Block the branch.

If `git cat-file` fails, run `git fetch origin <headRefOid>`. If that also fails, use the
degraded check below.

In degraded mode there is no `headRefOid`. Use the merge result instead:

```bash
git diff --stat origin/<default> $(git merge-tree --write-tree origin/<default> <branch>)
```

This prints the content that the branch adds and the default branch does not have. Empty

From Dzhuneyt/skills, MIT.

More from Dzhuneyt/skills