sebjacobs/branch-audit

Branch Audit

Produces a categorised branch status table, then stops. Does not delete or modify anything unless the user explicitly asks.

---

Steps

1 — Get all local branches (excluding main)

git branch --format='%(refname:short)' | grep -v '^main$'

2 — For each branch, check merged status

Two checks are needed — git branch --merged only catches merge-commit merges, not rebase fast-forwards:

# Check 1: is the branch an ancestor of main? (merge-commit merge)
git merge-base --is-ancestor <branch> main && echo "ANCESTOR"

# Check 2: is the diff empty? (rebase fast-forward — changes are on main, branch is stale)
git diff main...<branch> --stat

A branch is safe to delete if either:

• It is an ancestor of main (merge-base returns true), OR
• git diff main...<branch> --stat produces no output (empty diff)

3 — Cross-reference with GitHub PR state

gh pr list --state all --limit 100 --json number,title,headRefName,state,mergedAt

Map each branch to its PR (if any). PR states:

• OPEN — active work, do not touch
• MERGED — PR merged; if diff is also empty, safe to delete
• CLOSED (not merged) — abandoned PR; flag for decision
• No PR — has changes but was never proposed; flag for decision

4 — Output the categorised table

Present results in three sections:

Safe to delete — empty diff or merged ancestor. No risk. | Branch | PR | Notes | |--------|-----|-------|

Active — open PR, leave alone | Branch | PR | Size (files changed) | |--------|-----|---------------------|

Needs a decision — closed/abandoned PR, or changes with no PR | Branch | PR state | Situation | |--------|----------|-----------|

For the "Needs a decision" rows, include a one-line assessment: e.g. "superseded by X", "orphaned — no PR, 3 files changed", "PR closed without merging".

5 — Stop

Do not delete, push, or propose any git commands. Present the table and ask the user what they'd like to do. If they say "delete the safe ones", proceed branch by branch — local first, then remote — confirming each group before acting.

---

Notes

• Run this from the repo root
• Works in any git repo with a main branch; if the default branch is master or something else, adjust the main references
• Remote-only branches (no local checkout) appear in git branch -a with remotes/origin/ prefix — include them in the audit but note they are remote-only
• If gh is not available, skip the PR cross-reference and note that PRs could not be checked