Your feature branch has fallen behind main, and a teammate is waiting to review it. Merge joins the two histories with a merge commit and leaves your commits untouched; rebase replays your commits on top of the new tip for a linear history, as new commits. The code ends up identical, so rebase work only you have, and merge anything already pushed.
Bringing a branch up to date takes a few seconds of typing and, on plenty of teams, a long argument. Below, the two commands sit in no particular order, explained from Git's own reference documentation and the Pro Git book, so you can decide on the history you'll be happy to read later rather than on habit.
What a merge records
Git's own docs describe merge as joining two or more development histories together. In practice, git merge incorporates changes from the named commits into the branch you're on. Nothing that already exists is rewritten. Your commits keep their identities, and so do everyone else's.
When both branches have moved on, the Pro Git book explains that a standard merge does a three-way merge against the common ancestor of the two branches, then creates a new snapshot and a new commit to tie them together. That merge commit is the visible record that two lines of work met at that point, and it stays in the log for anyone who looks later.
When only one side has moved, things are simpler. A fast-forward merge doesn't create a merge commit at all; the branch just catches up. If you'd like to be certain about what a merge will do before anything lands, the docs suggest pairing --no-ff with --no-commit, so you can be sure the branch isn't changed by the merge command itself.
What a rebase rewrites
Git's docs describe rebase as reapplying commits on top of another base tip. Rather than tying two histories together, git rebase picks up your commits and plays them again from a new starting point, one after another.
The Pro Git book puts the difference neatly: rebasing replays changes in the order they were introduced, while merging takes the endpoints and merges them. The result, in the book's words, is a cleaner, linear-looking history. Read the log afterwards and your feature looks as if it was started from the latest work, with no merge commit in the middle.
Because the replay happens commit by commit, a rebase can stop partway when one of those commits clashes with the new base. That's why it comes with its own set of controls: continue, skip, abort, quit, edit-todo and show-current-patch. Abort is the one to remember, since it takes you back to where you were before you started.
The catch: same snapshot, different story
Here's the part that settles most arguments. The Pro Git book points out that both commands end on the same final snapshot. Merge your branch or rebase it, and the files at the tip are identical. The only thing that differs is the recorded history.
So the decision isn't about the quality or safety of the code itself. It's about what you want the log to say. Merge keeps a faithful record of how the work happened, branches and all. Rebase tells a tidier story in which the work arrives in a straight line. Both are honest about the code; they differ in how much of the journey they keep.
Once you see it that way, team debates get much shorter. Agree on the shape of history you'd like to read months from now, when you're hunting for the commit that broke something, and the command follows from that. Some teams want the full record for auditing who did what and when; others want a log a newcomer can read top to bottom. Both are reasonable, and both are reachable with either command used consistently.
The rewritten commits trap
There's one mistake that turns a tidy habit into a team problem. The Pro Git book explains that rebasing abandons existing commits and creates new, similar ones. On your own machine, before anyone else has seen them, that's harmless. On work you've already pushed, it's risky, because anyone who built on the old commits now has history that no longer matches yours.
That's the reason behind the usual rule of thumb: rebase what only you have, merge what others can see. If you ever do need to rebase shared work, tell the people on that branch before you push it, not after they've found out the hard way.
A quick check before any rebase saves most of the pain: could anyone else have pulled this branch? If the answer is yes, or you're not sure, merge instead. You lose a little tidiness in the log and keep everyone's history intact.
Merge and rebase at a glance
Each command is listed alphabetically, in no particular order, with what Git's documentation says it does.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
| Tool | What it does to history | Where it fits |
|---|---|---|
| git merge | Join histories, keeps branch shape | Shared branches and a full record of the work |
| git rebase | Reapply commits on a new base, linear history | Local work you want to read as a straight line |
git merge
Best for: Keeping every existing commit unchanged; Git's own docs describe merge as joining two or more development histories together.
git rebase
Best for: Tidying local work before review; Git's own docs describe rebase as reapplying commits on top of another base tip.
A house rule your team can agree on
Write the rule down in one sentence and put it in your contributing notes: rebase your own local branch onto the latest main before you open a pull request, and merge once the branch is shared. That gives reviewers the linear-looking history the Pro Git book describes, without anyone's pushed commits being replaced underneath them.
If you're newer to this, practise on a throwaway branch first, and keep abort in mind for when a rebase stops partway. When it does stop on a clash, show-current-patch tells you which of your commits it was replaying, which makes the conflict far easier to understand. My guide on how to use GitHub covers the everyday workflow around pull requests, and if your team is still deciding where the code lives, GitLab vs GitHub and GitHub vs Bitbucket compare popular places to host it.
Do you make Git tools or developer workflow software? Tool makers can ask to be considered for a featured place on this list.
Want your tool on this list? Featured spots and reviews here are paid partnerships. Here's how to partner with me.
Frequently asked questions
Does rebase change my code?
No. The Pro Git book says merge and rebase end on the same final snapshot; only the recorded history differs.
Is it safe to rebase a branch I've already pushed?
It's risky. Rebasing abandons existing commits and creates new, similar ones, so anyone working from the old commits ends up with history that no longer matches.
When does a merge not create a merge commit?
When it's a fast-forward. Git's docs say fast-forward merges don't create a merge commit.
How do I get out of a rebase that's gone wrong?
Rebase has its own controls, including abort, continue, skip and quit. Abort returns you to the state before the rebase began.
What is a three-way merge?
It's how a standard merge works when both branches have moved on: Git works from the two branch tips and their common ancestor, then creates a new snapshot and commit, as the Pro Git book explains.
Why do people rebase at all?
The Pro Git book says rebasing gives a cleaner, linear-looking history, which is easier to scan in the log.
