Git Rebase vs Merge
debt(d9/e5/b5/t7)
Closest to 'silent in production until users hit it' (d9). The detection_hints confirm automated detection is 'no', with the only code pattern being 'git push --force on shared branches' — which is already the symptom, not the prevention. There is no linter or SAST tool that reliably catches a rebase on a shared branch before it happens. Teammates only discover the problem when they try to pull and find diverged history.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix is conceptually simple (use merge for shared branches), but remediation after a bad rebase on a shared branch requires every affected collaborator to reset their local copy, reconcile diverged history, and potentially recover lost commits. This is a multi-person, multi-step coordination effort — beyond a one-line fix but not quite an architectural rework.
Closest to 'persistent productivity tax' (b5). The choice of rebase vs merge strategy affects every developer on the team and every branch integration workflow. A team that adopts the wrong convention (e.g. always-rebase on shared branches) pays an ongoing tax in force-push coordination, history confusion, and onboarding friction. It applies broadly across the cli context but doesn't reshape system architecture.
Closest to 'serious trap (contradicts how a similar concept works elsewhere)' (t7). The misconception field states it directly: 'Rebase is always cleaner than merge' — a belief that is actively reinforced by tutorials promoting linear history. The trap is that the 'cleaner' operation silently destroys shared history context for collaborators, contradicting the expectation that a history-tidying operation is safe. This is a well-documented gotcha that many developers only learn after causing a team incident.
Also Known As
TL;DR
Explanation
git merge creates a merge commit that joins two branch histories — history is preserved exactly. git rebase replays feature branch commits on top of the target, rewriting SHAs — produces a clean linear history but changes commit identity. Interactive rebase (git rebase -i) allows squashing, reordering, and editing commits. Golden rule: never rebase commits that have been pushed to a shared branch — others' history diverges. Rebase is preferred for local cleanup; merge is safer for shared branches.
Common Misconception
Why It Matters
Common Mistakes
- Rebasing a branch others are working on — forces force-push and history divergence.
- Using git pull --rebase without understanding that it replays local commits on the remote — can cause conflicts.
- Squashing too aggressively — losing useful incremental commits that explain why a change was made.
Avoid When
- Never rebase commits that have already been pushed to a shared branch — it rewrites history others depend on.
- Avoid force-pushing to main or develop — it overwrites work and breaks others' local copies.
When To Use
- Use rebase to clean up local feature branch commits before opening a pull request.
- Use merge to integrate a completed feature into a shared branch — preserves context.
Code Examples
# Rebasing a shared branch others are using
git checkout main
git rebase origin/develop # rewrites main — force-push required
git push --force origin main # breaks everyone else's local main# Local feature branch cleanup before PR
git checkout feature/my-feature
git rebase -i main # squash WIP commits, clean up messages
git push origin feature/my-feature # first push — safe to rebase
# Merging into main (preserves feature branch context)
git checkout main
git merge --no-ff feature/my-feature # explicit merge commit