Start.dev
Back to blog

Git merge vs rebase: which to use, and when

Git merge vs rebase in plain words: what each does to your history, when to use which, and the one rule that keeps rebase safe.

Ariel Weinberger
Ariel Weinberger · 6 min read

You have a branch, and main has moved on since you started it. Should you merge or rebase?

Short answer: both bring the changes from one branch into another. Merge keeps the history exactly as it happened and adds a merge commit. Rebase rewrites your branch's commits so they look like they started from the latest main. Merge is the safe default. Rebase is for tidying your own branch before you share it.

This post shows what each command does to your history, when to reach for each one, and the one rule that keeps rebase from causing trouble. If branches are new to you, start with Git for beginners: 10 commands.

The situation

You created a branch called feature from main and made two commits, C and D. Meanwhile, someone else added commit E to main.

          C---D   feature
         /
    A---B---E     main

Your branch doesn't have E yet. You want to combine the two lines of work. That is where merge and rebase differ.

What git merge does

Merge takes both lines of history and joins them with a new commit.

git switch feature
git merge main
          C---D---M   feature
         /       /
    A---B---E----     main

M is a merge commit. It has two parents, D and E. Nothing you already committed changes. History shows exactly what happened: you branched, you worked, and you brought main back in.

If main hadn't moved, Git wouldn't need M at all. It would just slide the branch pointer forward. That is a fast-forward merge, covered in Merging With A Fast Forward (opens in a new tab). The version with a merge commit is in Merge Commits (opens in a new tab).

What git rebase does

Rebase takes your commits and replays them, one at a time, on top of the latest main.

git switch feature
git rebase main
                C'--D'   feature
               /
    A---B---E            main

C' and D' have the same changes as C and D, but they are new commits with new ids. The old C and D are gone from the branch. History now reads as a straight line, as if you had started your branch after E.

That is the key difference. Merge adds a commit. Rebase replaces commits.

Merge vs rebase at a glance

git mergegit rebase
What it doesJoins two branches with a merge commitReplays your commits on top of another branch
Your existing commitsUnchangedReplaced with new copies
History shapeShows the branch and the joinOne straight line
ConflictsResolved once, in the mergePossibly once per replayed commit
Safe on shared branches?YesNo, only on commits nobody else has
Easy to undo?Yes, it is one commitHarder, the old commits are no longer on the branch

The one rule: don't rebase shared commits

Rebase rewrites commits. If you have already pushed a branch and someone else has pulled it, their copy still has the old C and D. Your copy now has C' and D'. Git sees those as completely different commits, and the next pull becomes a mess of duplicates and conflicts.

So the rule is simple: only rebase commits that exist only on your machine, or on a branch that only you use.

If you do rebase a branch you already pushed, and you are sure no one else is using it, you will need to force-push. Use the safer version, which refuses to overwrite work you haven't seen:

git push --force-with-lease

Never force-push to main or any branch other people share.

When to use merge

  • Bringing a finished branch into main. This is the everyday case, and usually happens through a pull request. Pull Requests And The Daily Workflow (opens in a new tab) covers that flow.
  • Any branch other people are working on. Merge never rewrites what they already have.
  • When you are unsure. Merge is the choice you can't really get wrong. The worst outcome is an extra commit in the history.

When to use rebase

  • Updating your own branch before you open a pull request. Rebasing on the latest main means your branch applies cleanly and reviewers see only your changes.
  • Pulling without a merge commit. If you committed locally and a teammate pushed to the same branch, git pull --rebase puts your unpushed commits on top of theirs instead of adding a merge commit.
  • Keeping a straight history, if your team prefers it. Some teams merge everything, some rebase before merging. Follow what your team already does.

Handling conflicts during a rebase

Conflicts work almost the same way as in a merge. Git stops, marks the conflicting lines, and waits for you. The difference is that rebase replays commits one by one, so you might stop more than once.

# fix the conflicted files, then:
git add .
git rebase --continue
 
# or give up and go back to where you started:
git rebase --abort

--abort is your safety net. It puts the branch back exactly as it was before the rebase. If you haven't resolved a conflict before, practise in Resolving A Merge Conflict (opens in a new tab) first. The editing part is identical.

A good default workflow

If you want one habit to start with:

  1. Do your work on a branch.
  2. Before opening a pull request, update it with git rebase main while it is still only yours. Or use git merge main if you have already shared it.
  3. Merge the finished branch into main through a pull request.

That gives you clean branches without ever rewriting something another person depends on.

Common mistakes

  • Rebasing main itself. You almost never want to rewrite the shared branch. Rebase your feature branch onto main, not the other way round.
  • Rebasing a branch someone else pulled. Their history and yours split apart. Merge instead.
  • Using git push --force out of habit. Prefer --force-with-lease, and only on your own branch.
  • Panicking mid-rebase. If it goes wrong, git rebase --abort gets you back to the start.
  • Thinking rebase loses your changes. It keeps the changes and makes new commits for them. What changes is the commit ids and the order.

Quick recap

  • Both merge and rebase combine work from two branches.
  • Merge adds a merge commit and keeps history as it happened.
  • Rebase replays your commits on top of another branch and gives a straight line.
  • Never rebase commits that other people already have.
  • Merge is the safe default. Rebase is for tidying your own branch before you share it.

Frequently asked questions

Is git rebase better than git merge?

Neither is better. They solve the same problem in different ways. Merge is safer and keeps full history. Rebase gives a tidier history but rewrites commits, so it only belongs on branches you haven't shared.

Does rebase delete my commits?

It replaces them with new commits that contain the same changes. The old commits are no longer on your branch, which is why rebasing shared work causes problems.

What does git pull --rebase do?

It fetches the remote changes, then replays your local unpushed commits on top of them instead of creating a merge commit. It is a common way to keep a shared branch's history straight.

How do I undo a rebase?

During the rebase, run git rebase --abort. After it has finished, git reflog shows where your branch pointed before, and you can reset back to that commit. That is an advanced step, so take it slowly.

Should beginners use rebase?

Learn merge first. It covers almost everything you need. Add rebase once branches, merges and conflicts feel comfortable, and start by using it only on your own local branches.

Practice

The Learn Git course teaches the merge side of this post step by step. Make a branch in Creating And Switching Branches (opens in a new tab), merge it with Merging With A Fast Forward (opens in a new tab) and Merge Commits (opens in a new tab), then fix a conflict in Resolving A Merge Conflict (opens in a new tab). Once those feel easy, try git rebase main on a practice branch of your own and compare the history with git log --oneline --graph.

Keep going

Learn Git (opens in a new tab) takes you from your first commit to branches, merges, remotes and pull requests. It is the Git you will use every day on a team.

Level up your coding skills

Jump into interactive courses and start building real-world projects.

Start learning

Related posts

Git has hundreds of commands, but you only need about ten. Learn the everyday Git commands for saving, reviewing, branching and sharing your work.
Ariel Weinberger
Ariel Weinberger · 5 min read
Stuck watching tutorials but unable to build alone? Learn the four causes of tutorial hell, how start.dev solves each, and a weekly routine to break out.
Ariel Weinberger
Ariel Weinberger · 6 min read
A one-hour coding practice you can repeat on a weeknight: recall, one exercise you write, a short note, and a start line for tomorrow.
Ariel Weinberger
Ariel Weinberger · 7 min read