Skip to main content
Download
Branching

Git merge vs rebase: which one should you use?

Merge and rebase both combine branches, but they leave a different history. The difference in a diagram, the golden rule, and when to pick each one.

By Anaïs Sparesotto (opens in a new window)Published 8 min read

The short answer: git merge and git rebase both bring the work from one branch into another and leave you with the same files, but with a different history. git merge adds a merge commit and keeps a record of where the branches split, while git rebase replays your commits on top of the other branch to get a straight line, rewriting them along the way.

So the choice isn't about the end result, it's about readability: what history does your team want to read six months from now? And one rule is not up for debate: never rebase commits other people already have.

What each command does to your history

Say you made two commits on a contact-form branch while a "Fix the footer" commit landed on main. The two branches have diverged:

Terminal
git log --oneline --graph --all* 5d9daab (HEAD -> main) Fix the footer| * 11d5bd7 (contact-form) Validate the email address| * c034a17 Add the contact form|/* 0cfdd7a Create the home page
Two Git histories: on the left, merge creates a merge commit joining the branches; on the right, rebase replays the commits into a straight line.
Same files in the end, different history.

git merge: a merge commit

From main, git merge joins the two branches in a new commit that has two parents:

Terminal
git merge contact-form# (output shortened)Merge made by the 'ort' strategy.git log --oneline --graph*   715fe47 (HEAD -> main) Merge branch 'contact-form'|\| * 11d5bd7 (contact-form) Validate the email address| * c034a17 Add the contact form* | 5d9daab Fix the footer|/* 0cfdd7a Create the home page

Git first opens your editor with a suggested message: save and close to confirm. No existing commit changes, and the history shows that two lines of work happened in parallel. The downside: on a busy project, merge commits pile up and the graph gets hard to follow. More in git merge explained.

git rebase: a straight line

From your branch, git rebase main moves it to the tip of main and replays your commits one by one:

Terminal
git switch contact-formSwitched to branch 'contact-form'git rebase mainSuccessfully rebased and updated refs/heads/contact-form.git log --oneline --graph --all* 6599580 (HEAD -> contact-form) Validate the email address* e295b79 Add the contact form* 5d9daab (main) Fix the footer* 0cfdd7a Create the home page

Look at the hashes: c034a17 is now e295b79, and 11d5bd7 is now 6599580. These are brand new commits: same changes, same messages, different parent. Back on main, git merge contact-form now answers Fast-forward, with no merge commit. See also git rebase explained.

Git merge vs rebase at a glance

git mergegit rebase
Resulting historyBranches and merge commitsOne straight line
Existing commitsUntouchedCopied, with new hashes
ConflictsResolved once, in the merge commitResolved commit by commit
On a shared branchSafeAvoid
Pushing afterwardsgit pushgit push --force-with-lease if the branch was already pushed

The golden rule: never rebase shared commits

A rebase swaps commits for copies. If someone else has the originals, you're in trouble: to publish your version you have to force push, which removes the old commits from the remote branch. The next time your teammates pull, every commit shows up twice, and anything pushed in the meantime can vanish from the branch.

Hence the rule: never rebase commits that are already pushed to a shared branch (main, develop, or any branch other people work on). You can freely rebase:

  • local commits you haven't pushed yet;
  • your own branch, even after pushing it, as long as nobody else works on it.

When in doubt, merge: it never rewrites anything.

Handling conflicts during a rebase

Since a rebase replays your commits one at a time, it can stop at any of them. Here, your "Link to the contact form" commit edits the same footer line as main:

Terminal
git rebase main# (output shortened)CONFLICT (content): Merge conflict in index.htmlerror: could not apply c4fbb1b... Link to the contact form

The conflict markers look the same as with a merge, but the sides are flipped: during a rebase, the HEAD side shows main (plus any commits already replayed), and the other side is the commit Git is replaying.

Terminal
cat index.html<h1>My site</h1><<<<<<< HEAD<footer>(c) 2026 My site</footer>=======<footer>(c) 2026 - <a href="contact.html">Contact</a></footer>>>>>>>> c4fbb1b (Link to the contact form)

Keep what should stay (here, both changes), delete the markers, then:

Terminal
git add index.htmlgit rebase --continue[detached HEAD fc76630] Link to the contact form 1 file changed, 1 insertion(+), 1 deletion(-)Successfully rebased and updated refs/heads/contact-form.

Git opens your editor to confirm the commit message, then moves on to the next commit. Don't worry about detached HEAD: Git works off-branch during the rebase and puts your branch back at the end. Want out? git rebase --abort returns your branch to exactly where it was before you started, and git rebase --skip drops the commit being replayed. Reading and resolving the conflict itself works just like a merge: see how to resolve a Git merge conflict.

git pull --rebase and the pull.rebase setting

git pull runs git fetch and then, by default, a merge. If a teammate pushed while you were committing locally, every sync adds a pointless Merge branch 'main' of ... commit. Recent versions of Git won't even pick for you anymore when branches diverge: fatal: Need to specify how to reconcile divergent branches.

git pull --rebase replays your local commits on top of the ones you just fetched instead:

Terminal
git pull --rebaseSuccessfully rebased and updated refs/heads/main.git log --oneline --graph* b5a3c04 (HEAD -> main) Add the site map* ab6807c (origin/main, origin/HEAD) Update the README* ec9dc12 Create the home page

This rebase follows the golden rule: only your unpushed commits get replayed. To make it the default, run git config --global pull.rebase true once (drop --global to set it for the current repository only; false goes back to merging). If you have uncommitted changes, git pull --rebase refuses to start: commit them or set them aside with git stash first.

After a rebase: git push --force-with-lease

You had already pushed your own branch (as a backup, or to open a pull request), then rebased it. The remote still has the old commits, so a plain git push gets rejected:

Terminal
git push# (output shortened) ! [rejected]        contact-form -> contact-form (non-fast-forward)

The full message suggests git pull, but that would be a mistake here: you'd end up with every commit twice, plus a merge commit. What you want is to replace the remote branch with your version:

Terminal
git push --force-with-lease# (output shortened) + 4de2e4a...a631d17 contact-form -> contact-form (forced update)

--force-with-lease is the careful version of --force: Git only overwrites the remote branch if it hasn't moved since you last fetched it. If someone pushed to it in the meantime, the push is rejected with (stale info) instead of wiping out their work. One catch: a git fetch in between (yours, or one your editor runs in the background) defeats that check, so add --force-if-includes to make Git also verify that you've actually integrated those commits. Other reasons a push gets rejected: failed to push some refs.

Picking a team convention

Merge and rebase aren't mutually exclusive. What matters is agreeing on one rule and writing it down, in your README or contributing guide. Three conventions are common:

  1. Always merge: every branch comes in through a merge commit (git merge --no-ff creates one even when a fast-forward is possible). Nothing gets rewritten: the easiest option for a team new to Git.
  2. Rebase, then fast-forward: everyone rebases their branch onto main, then integrates it with git merge --ff-only, which refuses if the branch isn't up to date. main stays a straight line.
  3. Squash: all the branch's commits become a single commit when it's integrated (git merge --squash). A straight line, but the step-by-step detail is gone from main.

On GitHub, these are the three merge options on a pull request ("Create a merge commit", "Rebase and merge", "Squash and merge"), and a repository can allow just one. Whatever you pick, make sure everyone sets pull.rebase the same way. For the bigger picture on organizing branches, read the Git branching workflow.

Frequently asked questions

What is the difference between git merge and git rebase?

git merge joins two branches in a merge commit without touching existing commits. git rebase copies your commits onto the tip of the other branch, so the history becomes linear. The files you end up with are the same.

Can git rebase lose my work?

Rarely, as long as it's your own commits: right after a rebase, git reset --hard ORIG_HEAD puts your branch back the way it was (it also wipes uncommitted changes), and git reflog keeps track of the old commits. The real danger is shared branches.

Should I use git pull --rebase?

It's a good habit: no merge commit every time you sync, and only your unpushed commits get replayed. To turn it on everywhere, run git config --global pull.rebase true.

How do I cancel a rebase in progress?

Run git rebase --abort. Your branch goes back to where it was before the rebase, even if you had already resolved some of the conflicts.

Why is git push rejected after a rebase?

The remote still has your old commits, and your branch no longer contains them. If the branch is yours alone, push with git push --force-with-lease. If others work on it, don't force anything: go back to the state before the rebase and merge instead.

From reading to practice

Type these commands for real in the GitQuest Academy simulated terminal: free, nothing to install, with a certificate at the end.

A

GitQuest is created by Anaïs (nouvelle fenêtre), web developer and head of education, specializing in tech training and digital accessibility.