| name | rebase-origin-main |
| description | Use when rebasing the current branch onto origin/main, including resolving merge conflicts along the way |
| metadata | {"internal":true} |
Rebase with origin/main
Overview
Fetches the latest origin/main, rebases the current branch onto it, and resolves every conflict that arises — one commit at a time — until the rebase completes cleanly.
Warning: Rebase Flips ours/theirs
During a rebase, git's labels are inverted from what you expect:
| Label | Means |
|---|
HEAD / ours (top of conflict) | origin/main — the base being rebased onto |
theirs (bottom of conflict) | Your commit being replayed |
Always resolve conflicts to preserve the intent of your commit while incorporating origin/main's context.
Workflow
1. Fetch & Start
git fetch origin
git rebase origin/main
If the output says Successfully rebased — done. No conflicts.
2. Detect Conflicts
git status
Look for lines with both modified, added by us, deleted by them, etc.
3. Resolve Each Conflicted File
For each conflicted file:
- Read the file — find all conflict markers (
<<<<<<<, =======, >>>>>>>)
- Understand both sides:
- Above
======= (HEAD) = origin/main's version
- Below
======= = your commit's change
- Resolve by editing the file to the correct merged result — no conflict markers left
- Verify no conflict markers remain:
grep -En "<<<<<<<|=======|>>>>>>>" <file>
- Stage the resolved file:
git add <file>
If a conflict is ambiguous — where preserving both sides isn't clear — stop and ask the user before resolving.
4. Continue
After all conflicts in the current commit are staged:
git rebase --continue
Git will either move to the next commit (go back to step 2) or report success.
5. Handle Edge Cases
| Situation | Command |
|---|
| A commit becomes empty after resolution | git rebase --skip |
| You need to abort entirely | git rebase --abort |
| Binary file conflict | Show the user and ask which version to keep |
6. Verify
After a clean rebase, confirm the branch looks correct:
git log --oneline origin/main..HEAD
7. Fix CI
After a successful rebase, run the full CI suite locally to catch any breakage introduced by the rebase:
pnpm lint && pnpm typecheck && pnpm test && pnpm build
If anything fails, follow the fixing-ci skill workflow starting from Step 2 (Fix Loop) through Step 3 (Verify All): diagnose each failure, fix the root cause, verify, and commit atomically. Do not proceed to push until all checks pass locally — the push is handled by Step 8 below with --force-with-lease.
8. Push
Force-push with lease (safe force-push — aborts if someone else pushed since your last fetch):
git push --force-with-lease
Conflict Resolution Principles
- Prefer explicit over clever — when in doubt, keep both changes and adjust for correctness
- Deletions on main win if you also deleted the same thing (skip your no-op)
- Your additions win unless they conflict with a semantic change in main (e.g., a rename)
- Never silently discard either side — if a resolution loses meaningful code, flag it to the user
Common Mistakes
| Mistake | Fix |
|---|
| Leaving conflict markers in file | Grep for <<<<<<< before staging |
| Staging before fully reading the file | Read the full file first |
Assuming ours = your branch | It's inverted in rebase — ours is origin/main |
| Continuing without reviewing log | Always run git log --oneline origin/main..HEAD after |
