On this page
What Is Git Rebase (and When Should You Use It Instead of Merge)?
Merge preserves history with a merge commit; rebase replays your commits on top for a linear history. Learn the difference and when to use each.
Quick answer
- Merge combines branches and keeps a merge commit, preserving the full, true history.
- Rebase replays your commits onto the target branch, producing a clean, linear history.
- Rebase your own unpublished work for tidiness; merge (or squash-merge) shared work to preserve history safely.
What merge does
git merge joins two histories by creating a merge commit with two parents. It never rewrites history — every commit stays exactly as it was, and the merge commit records the join. The result is a “true” history, but one that can become a tangled web of merge commits and interleaved branches.
What rebase does
git rebase takes your branch’s commits and replays them, one by one, on top of the target branch’s tip, as if you’d started from there. It rewrites those commits (new hashes), producing a straight, linear history with no merge commits. The cost: history is rewritten, which is dangerous for commits others already have.
When to use each
Use rebase for your own unpublished work — keeping a feature branch up to date with main, or tidying commits before opening a pull request. Use merge (or squash-merge, which collapses your commits into one) when integrating shared branches, because rewriting history that others have pulled breaks their repositories. The practical rule: rebase local, merge shared.
Where this bites vibecoders
AI assistants often suggest
git rebaseor force-push to “fix” a messy branch without warning about the rule that matters: never rewrite history that’s already shared. Force-pushing a rebased branch that a teammate (or a collaborating agent) built on causes confusing conflicts and lost work. The safe habit: rebase only your own unpushed commits, and force-push only to your own branch with--force-with-lease.
Where AI coding assistants get this wrong
- Suggesting
git push --forceafter a rebase without explaining the shared-history danger. - Rebasing published branches, breaking collaborators.
- Using merge for trivial local tidy-ups and rebase for shared work — the opposite of the guidance.
- Squashing away meaningful history that future readers need.
Checklist
- Rebase local, unpublished commits for a clean history.
- Merge (or squash-merge) shared branches.
- Use
--force-with-lease, never plain--force, when you must force-push. - Don’t rewrite history others have already pulled.
- Keep commit history meaningful; don’t squash real decisions away.
FAQ
What is a merge commit?
A merge commit is a commit with two parents, created when Git combines two branches. It records that a merge happened and preserves both histories exactly. It’s what makes merge “non-destructive” to history.
Why do rebased commits get new hashes?
A commit’s hash is computed from its content and its parent. Rebasing changes each commit’s parent, so the hashes change even when the content doesn’t. That’s why rebasing is “rewriting history” and unsafe for shared branches.
What is squash-merge?
Squash-merge combines all of a branch’s commits into a single commit when merging, then merges that one commit. It gives a linear history without the rebase rewriting. Teams use it to keep main clean while preserving the fact that the branch’s commits were one logical change.