Branch Sync & Multi-Branch Management

Complete runbook and automation protocol to inspect all git branches, deep-preview branch changes, merge verified work into main, and synchronize all remaining active branches to the latest main state without creating merge conflicts or shredding uncommitted work.

Core Protocols

1. Audit & Inventory (check all branch)

Before touching any branch, establish a complete snapshot of all local and remote branches:

# Fetch latest state from all remotes
git fetch --all --prune

# Audit local and tracking branches (ahead/behind main)
git for-each-ref --format='%(refname:short) | ahead: %(ahead-behind:main) | commit: %(subject) (%(authordate:relative))' refs/heads/

• Identify active feature branches vs stale/merged branches.
• Check working tree cleanliness (git status --porcelain). If uncommitted changes exist, stash or commit before proceeding.

2. Deep Preview (preview sâu)

Inspect any branch thoroughly before merging to ensure code quality and impact safety:

• Diff Overview: git diff main...<branch> (shows changes introduced by <branch>).
• Commit History: git log main..<branch> --oneline --stat (shows commit breakdown).
• Symbol & Architecture Impact:
  • Run codegraph impact "<symbol>" to check for breaking exported APIs across the branch boundary.
• Dry-run Conflict Pre-check:

  # Check if merging <branch> into main will cause conflicts BEFORE doing it
  git merge-tree $(git merge-base main <branch>) main <branch>

  If output contains <<<<<<<, conflicts will occur. Inspect conflicting files first.

3. Safe Merge to Main (merge về main)

Once a branch preview is validated and conflict-free:

1. Ensure main branch is up-to-date:

   git checkout main
   git pull --ff-only origin main

2. Merge the feature branch safely:

   # Prefer fast-forward if possible, otherwise clean merge
   git merge --no-ff <branch> -m "feat: merge <branch> into main"

3. Run verification (smoke test / 8sync doctor / build):

   cargo build --release  # or project test command

4. Push updated main to remote:

   git push origin main

4. Zero-Conflict Multi-Branch Sync (sync all branch)

After main has advanced, synchronize all remaining active local/remote branches to match the latest main:

For each target branch <branch> (excluding main, master, or retired branches):

# 1. Checkout branch
git checkout <branch>

# 2. Dry-run conflict test with latest main
git merge-tree $(git merge-base main <branch>) <branch> main

# 3. If clean, merge main into branch
git merge main -m "sync: update <branch> with latest main"

# 4. Push updated branch to remote (if tracked)
git push origin <branch>

Safeguards & Conflict Prevention:

• Uncommitted work on branch: Auto-stash before checkout (git stash save "branch-sync-autostash-<branch>"), pop after sync (git stash pop).
• Conflict detected during dry-run: NEVER force-merge or leave merge conflict markers. Pause the sync for that specific branch, log the exact conflicting files, report to the user, and abort the merge for that branch (git merge --abort).
• Return to original branch: Always return the repository to the starting branch upon completion.

---

Automation Script

Use the bundled script assets/skills/branch-sync/scripts/branch_sync.py (or run via Python/bash) for fast, multi-branch audit and conflict-free sync execution:

python3 ~/.omp/skills/branch-sync/scripts/branch_sync.py --action audit
python3 ~/.omp/skills/branch-sync/scripts/branch_sync.py --action preview --branch <branch>
python3 ~/.omp/skills/branch-sync/scripts/branch_sync.py --action merge --branch <branch>
python3 ~/.omp/skills/branch-sync/scripts/branch_sync.py --action sync-all