How do I prune merged git branches with compass?

Table of Contents

The Orient pillar of the compass tool. Formalises the manual fetch/diff/cross-reference-against-fleet/delete workflow used for git-branch hygiene.

Question

How do I find and delete git branches (local and remote) that are already merged into origin/main, without accidentally deleting a branch another worktree is using?

Answer

Run compass.sh branches (or branches report) for a read-only report:

./projects/ores.compass/compass.sh branches report

It fetches with --prune, computes branches merged into origin/main for both local refs and origin/* remote refs, and buckets every branch:

  • Safe to delete – merged into origin/main, not the current branch, not main, and not checked out by any other fleet worktree.
  • Kept – with a reason: is the current branch, is main, checked out by WORKTREE_NAME (cross-referenced via git worktree list, same source compass fleet uses), or unmerged/active work.

Then prune the safe set:

./projects/ores.compass/compass.sh branches prune

Without -y this is a dry run – it only prints what would be deleted. Add -y to actually delete, local first (git branch -d, which refuses branches with unmerged commits as a safety net even if the --merged computation above was somehow wrong) then remote (git push origin --delete), printing what was deleted and, again, what was left alone and why.

Script

projects/ores.compass/compass.sh branches calls src/compass_branches.py (run=/=cmd_report=/=cmd_prune), using git for-each-ref=/=git branch --merged origin/main for the merge computation and git worktree list --porcelain for fleet cross-reference (same source as compass fleet).

Tested by

Manually exercised against the live branch set (43 local/remote candidates): report and prune matched the expected safe-delete set, correctly leaving fleet-owned, unmerged, main, and current branches alone.

See also

Emacs 29.3 (Org mode 9.6.15)