Skip to content

Git Branch / Worktree Hygiene

The canonical repository must remain clean and boring.

Allowed standing local branches:

  • main
  • release/v0.1.x <- or what ever is the latest

Everything else must either:

  1. be attached to an active governed worktree for current work, or
  2. be removed after proving it is merged or intentionally abandoned.

Rules

  • Do not develop directly in the canonical checkout.
  • Do not leave merged feature/fix/chore branches behind.
  • Do not leave dead worktrees behind.
  • Do not delete unmerged branches blindly.
  • Do not use git stash.
  • Do not use git rebase.
  • Do not use force push.
  • Do not use destructive reset to clean branch state.

Cleanup Process

From the canonical repository:

git status --short
git fetch origin --prune
git worktree list
git branch --merged release/v0.1.x <- example
git branch --no-merged release/v0.1.x <- example
git branch --merged main
git branch --no-merged main

For every non-main / non-release/v0.N.x branch

Classify it as:

ACTIVE_WORKTREE
MERGED
UNMERGED_ACTIVE
UNMERGED_ABANDONED
UNKNOWN

ACTIVE_WORKTREE

Inspect the worktree:

cd /path/to/worktree
git status --short
git log --oneline --decorate -5

If work is still active, keep it.

If work is merged and the worktree is clean:

cd /path/to/canonical/repo
git worktree remove /path/to/worktree
git branch -d <branch>

MERGED

Delete safely:

git branch -d <branch>

UNMERGED_ACTIVE

Keep only if there is a real active task / Bead / MR.

UNMERGED_ABANDONED

First prove there is no unique value that must be preserved:

git log --oneline release/v0.1.x..<branch>

If unique commits exist, inspect them before deletion.

Only remove after explicit disposition.

UNKNOWN

Do not delete.

Investigate:

git log --oneline --decorate --graph <branch> -10
git log --oneline release/v0.1.x..<branch>
git log --oneline main..<branch>

Final Cleanup

After removing dead worktrees:

git worktree prune
git fetch origin --prune

Recheck:

git branch
git worktree list
git status --short

Required End State

CANONICAL_BRANCH=release/v0.1.x
CANONICAL_REPO_CLEAN=YES

STANDING_BRANCHES:
main
release/v0.1.x

OTHER_LOCAL_BRANCHES:
ONLY_ACTIVE_GOVERNED_WORK=YES

MERGED_BRANCHES_PRUNED=YES
DEAD_WORKTREES=0
STALE_WORKTREE_METADATA=NO
UNMERGED_UNOWNED_BRANCHES=0

Final Law

main and release/v0.1.x are the only standing branches.

All other branches are temporary execution state.

WORK COMPLETE means:

MR merged
→ worktree removed
→ local branch removed
→ remote branch pruned where appropriate
→ canonical checkout clean

Do not accumulate branch history as filesystem clutter. Git already preserves the history.