sync-local-branches

Sync Local Branches

Overview

Fast-forward every local branch with an upstream, then delete local branches that are clearly merged:

1. Upstream tracking branch is gone (standard PR-merged + remote-deleted signal).
2. No upstream tracking, but every commit is already in the primary branch (catches squash-merged branches that never had upstream set, e.g. branches created locally and pushed via gh pr create).

When to Use

• After several PRs have been merged upstream and local branches pile up
• User says "sync all branches", "pull all branches", "clean up merged branches"
• Post-release housekeeping on a working clone

When NOT to Use

• Repo has uncommitted/staged changes → abort first, don't silently stash
• User wants to delete branches merged by git merge but whose remote still exists → use git branch --merged main logic instead
• User is on a detached HEAD

Procedure

1. Pre-flight: must be in a git repo; working tree must be clean.
2. git fetch --all --prune — update remote refs, remove deleted remote branches locally.
3. For each local branch with an upstream that is not gone:
   • Fast-forward via git fetch . <upstream>:<branch> (works without checkout; refuses non-FF, safe).
4. For the current branch, run git merge --ff-only @{u} (purely local — fetch already happened in step 2).
5. Delete merged branches without asking:
   • Branches whose upstream is gone (standard "remote merged + remote deleted" case).
   • Branches with no upstream whose every commit is already in the primary branch (git cherry primary branch shows no + lines — covers squash-merge with missing upstream tracking).
   • Use git branch -D because squash-merged branches are not recognized as merged by -d. Never delete the current branch or main/master/develop/trunk.
6. Detect stale worktrees — any non-current worktree whose branch either (a) has upstream gone, or (b) has the same tip as the primary branch (merged). Only report them; never auto-remove.
7. Print a summary: updated branches, skipped branches (with reason), deleted branches (with reason), and any stale worktrees flagged for review.

After the Script Runs

If the summary lists stale worktrees, ask the user whether to clean them up before doing anything. For each confirmed entry, run:

git worktree remove <path>
git branch -D <branch>

Never remove a worktree without confirmation — the user may have uncommitted work or deliberate parked state there.

Script

The bundled script is at ${CLAUDE_PLUGIN_ROOT}/skills/sync-local-branches/sync.sh. If that variable isn't expanded, locate sync.sh under the plugin's installation directory at skills/sync-local-branches/sync.sh. Run it from the target git repo's root:

bash <path-to-sync.sh>            # apply
bash <path-to-sync.sh> --dry-run  # preview

Key Logic (reference)

# Detect "remote merged & deleted" branches:
git branch -vv | awk '/: gone\]/ {print $1}' | sed 's/^\*\s*//'

# Detect "no upstream + already merged" (incl. squash merges):
# git cherry shows '+' for unmerged commits; no '+' lines = fully merged.
git cherry main feature-branch | grep -q '^+' || echo "merged — safe to delete"

# Fast-forward a non-checked-out branch safely:
git fetch . "origin/feature-x:feature-x"   # refuses non-FF, no checkout needed

Common Mistakes

Mistake	Fix
Using git branch --merged main to find merged branches	Misses squash merges. Use : gone] + git cherry instead.
Running git pull in a loop with git checkout	Slow, dirties reflog, may conflict. Use git fetch . up:branch.
Deleting with -d	Fails on squash-merged branches. Use -D after confirming upstream is gone or all commits are in primary.
Forgetting --prune on fetch	Upstream-gone detection won't work.
Deleting main/current branch	Always guard with an allowlist + current-branch check.

Safety

• Aborts on dirty working tree.
• Never deletes main, master, develop, trunk, or the current branch.
• Never auto-removes worktrees — stale worktrees are reported, not deleted.
• --dry-run prints what would be deleted without touching anything.
• Only fast-forwards; never rewrites or force-updates.