Git Rebase vs Merge: When to Use Each (and the Golden Rule)

CodexFuse Team · 2026-11-04T06:28:53.725Z · 14 min read min read

Every Git user eventually asks the same question: git rebase vs merge — which one should I use? Both commands integrate changes from one branch into another, but they do it in fundamentally different ways. Merge preserves your history exactly as it happened; rebase rewrites it into a clean, straight line. This guide explains what each one does to your repository, the golden rule that keeps you out of trouble, how conflicts behave in each, and a 10-second decision rule you can use forever. If you are still learning the basics, start with our Git beginner guide, then come back here.

What is the difference between git rebase and git merge?

Git merge creates a new commit with two parents that ties two branch histories together, preserving every commit exactly as it happened. Git rebase transplants a series of commits onto a different starting point, replaying them one by one so the history looks like one straight line. In short: merge records history, rebase rewrites it. (Developers search for this as both "git rebase vs merge" and "git merge vs rebase" — it is the same question either way.)

The Git documentation puts the rebase side this way, verbatim: "Transplant a series of commits onto a different starting point." And the Pro Git book draws the contrast sharply: "Rebasing replays changes from one line of work onto another in the order they were introduced, whereas merging takes the endpoints and merges them together." Merge keeps the fork-and-join shape of your work; rebase makes it look as if all the work happened in series, even when it originally happened in parallel.

What does git merge actually do to your history?

Git merge incorporates changes from the named commits into the current branch, and — except in a fast-forward case — ties the two histories together with a merge commit that has both of them as its parents. Your existing commits are never touched; the new commit simply records the two parent commits and the result of combining them.

This is why merge is the honest option. Nothing is rewritten, so the log tells the true story: when the branch was created, what state each branch was in, and exactly when they came together. That two-parent merge commit is a permanent historical marker you can inspect later with git log --graph, and no one downstream ever has to realign their copy of the repository.

There is one special case worth knowing. When the branch you are merging is simply ahead of your current branch, Git can do a fast-forward merge: it only updates the branch pointer to match the merged branch and creates no merge commit at all. The git-merge docs define the options precisely: --ff allows the fast-forward when possible, --no-ff creates a merge commit in every case even when a fast-forward would work, and --ff-only refuses to merge — exiting with a non-zero status — when a fast-forward is not possible.

What does git rebase actually do to your history?

Git rebase takes the commits on your branch and replays them one by one on top of another branch, producing brand-new commits with brand-new hashes. The Git documentation's own diagram shows the idea: commits A, B, C on your topic branch become A', B', C' on the new base. The apostrophes matter — those are different commits.

This is the sentence to burn into memory, from the Pro Git book: "When you rebase stuff, you're abandoning existing commits and creating new ones that are similar but different." The --force-rebase option makes the mechanics explicit too: it "ensures that the entire history of the rebased branch is composed of new commits." Rebase does not move commits; it recreates them.

The payoff is a perfectly linear log. Again, Pro Git: "If you examine the log of a rebased branch, it looks like a linear history: it appears that all the work happened in series, even when it originally happened in parallel." A straight-line history is easier to scan, easier to read with git log, and easier to debug with tools like git bisect. The price is that the original history is gone from the branch, and anyone who already pulled the old commits will see them diverge from your new ones.

When should you use git merge?

When should you use git merge? The short answer is: whenever the history itself is valuable, or whenever the branch is not yours alone. "When to use git merge" is the question developers ask when they want the safe default — and in four situations, merge genuinely is the right call.

• Integrating a finished feature into main. The merge commit documents the integration point and preserves the feature branch as a cohesive unit. Many teams use --no-ff here so the branch context survives even when a fast-forward would have been possible.
• Working on shared or public branches. If teammates have the branch checked out, merging never rewrites anything they already have. Rebase would force every one of them to realign their local copy.
• Preserving an exact audit trail. When you need to know exactly when branches converged — for compliance, incident reviews, or release notes — the merge commit is the evidence.
• Long-lived branches. Integration and release branches act as coordination points between teams, so they are almost always merged into, never rebased.

A useful bonus: if a branch already contains carefully resolved merge work, merging preserves that resolved state as one explicit event instead of replaying every conflict again, commit by commit.

When should you use git rebase?

When should you use git rebase? This is the "git rebase explained at the level that matters" part: rebase is the cleanup tool for branches you own alone. If you searched for "when to use git rebase" because your local branch is a mess of wip commits, this section is your answer — it is exactly the right tool, as long as the branch is unshared. Rebase shines in three situations, all before the branch is shared.

• Updating your feature branch with the latest main. Instead of stacking a merge commit on top every time main moves forward, rebase replays your commits onto the new tip so your branch stays fresh and the final merge is trivial.
• Cleaning up messy local commits before a pull request. Interactive rebase (git rebase -i HEAD~4) opens a todo list where you can squash ten "wip" commits into one, reorder them, fix messages, or drop experiments. Reviewers see the story you meant to tell, not the one you stumbled through.
• Keeping a linear team history. If your team prefers a straight-line main branch, the standard pattern is: rebase your feature onto main, then merge — which resolves as a clean fast-forward. For the PR workflow itself, our GitHub beginner guide shows how this fits the pull-request lifecycle.

The interactive todo list supports seven commands, straight from the git-rebase docs: pick keeps a commit as-is, reword edits just its message, edit stops so you can amend the commit, squash and fixup fold commits together, drop removes one, and break pauses the whole process. You start it with git rebase -i <after-this-commit> — the last commit you want to keep untouched.

What is the golden rule of rebasing?

The golden rule of rebasing, in the Pro Git book's exact words: "Do not rebase commits that exist outside your repository and that people may have based work on." In plain terms — the version teams usually memorize as "never rebase public branches" — rebase branches only you have seen; merge branches other people are using.

The reason is mechanical, not moral. Rebase creates new commits with new hashes, so after a rebase of a shared branch, your collaborators' copies still point at the abandoned commits. The Pro Git book describes the fallout verbatim: "If you push commits somewhere and others pull them down and base work on them, and then you rewrite those commits with git rebase and push them up again, your collaborators will have to re-merge their work and things will get messy when you try to pull their work back into yours."

The chapter closes with the pragmatic version of the rule: "You can get the best of both worlds: rebase local changes before pushing to clean up your work, but never rebase anything that you've pushed somewhere." Memorize that sentence and you will never cause a rebase disaster.

How do merge and rebase handle conflicts differently?

Both commands can hit the same conflict, but they resolve it in different rhythms. A merge conflict happens once, at the integration point; a rebase conflict can happen once per commit, because each commit is replayed separately. The table below is the comparison the quick guides usually skip.

That last row is the classic rebase trap, and it is documented verbatim in the git-rebase man page: "Because of this, when a merge conflict happens, the side reported as ours is the so-far rebased series, starting with <upstream>, and theirs is the working branch. In other words, the sides are swapped." If you resolve a rebase conflict and the sides feel backwards, they are — by design.

One more practical note: repeating the same conflict resolution across five replayed commits is the sign you should have merged instead. A long-lived branch with heavy conflict-resolution work is a merge-shaped problem, not a rebase-shaped one.

Git pull: should you rebase or merge?

Git pull is fetch plus integration, and you get to choose the integration. The git-pull docs list the four options verbatim: git pull --ff-only only does fast-forward updates and is the default when no reconcile method is configured; git pull --rebase runs rebase after fetching; git pull --no-rebase runs merge; git pull --squash runs merge with squashing.

You can set your preference permanently with pull.rebase. The current git-config docs (Git 2.56.0, released 2026-09-28) list four values: true rebases the current branch on top of the fetched branch instead of merging; false merges; merges (abbreviation m) rebases while keeping your local merge commits in the replay; and interactive (abbreviation i) runs the rebase in interactive mode. Note that preserve does not appear in the current documentation — if you find it in an old tutorial, it is not a valid value today.

For solo work and short-lived branches, git config pull.rebase true is a popular default: your local commits always land cleanly on top of the latest remote work. For shared branches, leave the default fast-forward-only behavior and merge deliberately. And if you push over SSH to a self-hosted remote, a tidy SSH config guide and a private VPS hosting box make a fine personal Git server.

The 10-second decision rule

When in doubt, ask one question: has anyone else seen this branch? If the answer is no, rebase freely; if the answer is yes — or you are not sure — merge. The decision table below covers the cases you will actually hit.

A quick word on that last row: git rebase --onto takes patches that diverged from one branch and replays them onto a completely different starting point. The classic example from the Pro Git book — git rebase --onto master server client — replays the client-only commits onto master as if they had been based there all along. You will not need it often, but when you do, nothing else substitutes.

How to recover from a rebase gone wrong

The first recovery is built in: git rebase --abort stops the rebase and returns your branch to its original state. Use it the moment a rebase feels out of control — mid-conflict, mid-confusion, or mid-regret. A merge has the equivalent escape hatch, git merge --abort.

The second recovery is a habit: before any ambitious rebase, create a backup branch pointing at your current work (git branch backup-before-rebase). It costs nothing, and it means "abort" is never your only option. The golden rule covers everyone else; the backup branch covers you.

Sources

Every command and quote in this article was verified against the primary documentation on 2026-11-03:

• git-scm.com/docs/git-merge — merge mechanics, the two-parent merge commit, and the --ff / --no-ff / --ff-only options.
• git-scm.com/docs/git-rebase — the "transplant" definition, interactive-mode commands, conflict recovery (--continue / --abort / --skip), the ours/theirs swap, and --onto.
• git-scm.com/book/en/v2/Git-Branching-Rebasing — Pro Git chapter 3.6: the linear-history and "abandoning existing commits" quotes, the golden rule, and the --onto example.
• git-scm.com/docs/git-pull — the four integration options and the --ff-only default.
• git-scm.com/docs/git-config — the pull.rebase values (true / merges / false / interactive).
• endoflife.date/git and versio.io — Git 2.56.0 as the current stable release (released 2026-09-28).
• atlassian.com/git/tutorials/merging-vs-rebasing — Atlassian's conceptual tutorial on both workflows.
• docs.github.com/en/get-started/using-git/about-git-rebase — GitHub Docs on rebasing and interactive rebase.

Frequently Asked Questions

Is git rebase better than git merge?

Neither is better — they solve different problems. Rebase gives you a clean, linear history on branches you own; merge preserves the true, auditable history of how branches came together. The Pro Git book's advice is the whole philosophy in one sentence: "rebase local changes before pushing to clean up your work, but never rebase anything that you've pushed somewhere."

Can I rebase a branch I have already pushed?

Only if nobody else has pulled it. The golden rule is "do not rebase commits that exist outside your repository and that people may have based work on." If the branch is yours alone and no teammate has fetched it, you can rebase and force-push safely. If anyone might have pulled it, merge instead.

Does git rebase delete my commits?

Rebase abandons your old commits and creates new ones that are similar but different — same changes, new hashes. The original commits become unreachable from the branch. That is exactly why rebasing shared branches is dangerous: everyone else's copy still references the abandoned commits.

Why do "ours" and "theirs" feel backwards during a rebase conflict?

Because during a rebase the sides are genuinely swapped. The git-rebase docs state it plainly: the side reported as "ours" is the so-far rebased series starting with the upstream, and "theirs" is your working branch. In a merge, "ours" is your current branch — the opposite of what a rebase conflict shows.

How do I make git pull always rebase?

Run git config pull.rebase true. After that, git pull fetches and rebases your local commits onto the latest remote work instead of creating merge commits. Use merges instead of true if you want your local merge commits carried through the rebase.