Rebase vs Merge

By Michael Samuel Naeem · April 28, 2025 · 5 min read

Two senior engineers argued rebase vs merge for twenty minutes in a PR comment thread. Both were right for different constraints: rebase gives readable git log main; merge preserves the fact that work happened in parallel on a branch. Team policy beats individual preference here.

What merge does

git checkout feature
git merge main

Creates merge commit combining histories—diamond graph preserved.

git checkout main
git merge --no-ff feature

--no-ff keeps explicit merge commit even if fast-forward possible—documents branch integration point.

Pros: no history rewrite; safe for shared branches; accurate timeline.

Cons: cluttered log; harder bisect through merge bubbles.

What rebase does

git checkout feature
git rebase main

Replays feature commits atop latest main—linear sequence as if you started from today's main.

Pros: clean log; easier git log --oneline; reviewable commit series.

Cons: rewrites SHAs—never rebase commits others pulled without coordination.

Golden rule

Do not rebase public shared branches. If anyone else commits on feature/login, merging is safer. Rebase only local or sole-owner branches before PR.

Pull request strategies on GitHub

Many teams use squash and merge on main for one changelog line per PR, rebase locally while developing.

Interactive rebase for cleanup

Before PR:

git rebase -i main

Squash WIP commits, reword messages to Conventional Commits, drop debug commits.

pick a1b2c3 feat(auth): add login form
squash d4e5f6 fix typo
reword g7h8i9 fix(auth): handle timeout

Result: professional commit series reviewers can follow.

Conflict handling

Rebase stops at each conflicting commit:

# fix files
git add .
git rebase --continue
# or abort
git rebase --abort

Merge conflicts during rebase differ from merge—conflicts replay per commit, sometimes repeatedly. Prefer small commits during rebase.

Updating feature branch with main

Option A — merge:

git merge origin/main

Option B — rebase (solo branch):

git fetch origin
git rebase origin/main
git push --force-with-lease

--force-with-lease refuses push if remote has unexpected commits—safer than --force.

Revert implications

Revert merge commit needs -m 1 parent specification. Rebased linear history simplifies git revert <sha> per commit.

Team policy template

Document in CONTRIBUTING.md:

1. main is protected; PR required
2. Squash merge to main
3. Rebase allowed on feature branches before review
4. No force-push to shared branches except feature with --force-with-lease
5. Release branches merge only, no rebase

Consistency matters more than which side "wins."

Release branch exception

Mobile release train may use short-lived release branch merging to main via merge commit—preserves release stabilization commits visibly. Trunk-based purists still keep branch under 48 hours.

Conflict psychology

Rebase conflicts replay per commit—multiple conflicts feel painful but produce cleaner history. Merge conflict once on merge commit—one painful moment.

Teaching juniors

Diagram branch graphs on whiteboard—visual learners grasp --ff-only vs merge commit faster than prose.

Automation

GitHub "Update branch" button merges main into PR—convenient but adds merge commits; prefer rebase button if enabled org-wide.

Signed commits and rebase

Rebase replays commits—GPG signatures invalidated unless configured to resign. Teams using signed commits policy should document whether merge-only trunk preserves signatures.

Bisect workflow

Linear history from rebase simplifies git bisect—merge-heavy main may skip merge commits with --no-merges first-parent walk; understand your graph before bisecting production regression.

Pair programming and shared branches

Two developers on same branch should merge main, not rebase, if both pushed—coordinate verbally before any force-push.

Bot automation

Dependabot PRs flood merge queue—auto-merge squash with conventional title keeps trunk readable despite high PR volume.

Graph visualizer

Use `git log --oneline --graph --all` in team docs screenshots—onboarding material showing merge vs rebase outcomes reduces abstract confusion for junior developers learning trunk workflow first week.

Rollout guidance

Team offsite agrees merge policy written within 24 hours—verbal consensus fades. GitHub branch settings enforce policy technically not only culturally—branch protection prevents merge commits if squash-only policy chosen.

Team practices

Shipping Git Rebase Vs Merge in production taught our team that documentation beats hero demos. We wrote runbooks covering failure modes, on-call steps, and rollback triggers before the second release, not after the first outage.

When reviewing PRs touching Git Rebase Vs Merge, we ask for measurable outcomes: latency, crash rate, or support ticket volume—not subjective feels faster. If metrics are unavailable, the PR includes a DevTools trace or load test snippet proving the change.

Onboarding engineers paste a checklist into their first Git Rebase Vs Merge PR description: environment setup verified, tests added or updated, accessibility spot-checked, and release notes drafted for user-visible changes.

We keep a living FAQ in the repo wiki for Git Rebase Vs Merge questions repeated in Slack more than twice. FAQ entries link to source files and Slack threads, reducing tribal knowledge and repeated explanations in code review.

Cross-functional review includes design for UX-facing work, security for auth or storage, and platform for native bridges. Git Rebase Vs Merge spans layers; skipping reviewers recreated bugs we fixed months ago.

Document team policy in CONTRIBUTING.md — mixed rebase/merge workflows create duplicate commits and broken bisect history.

Resources

• Git merge documentation
• Git rebase documentation
• Atlassian rebase vs merge guide
• GitHub merge options
• Pro Git book — rebasing