Skip to content
>_KernelBrief
Programming

Git Merge vs Rebase Explained: How Each Works, When to Use Them, With Examples

Git merge vs rebase: how each combines branches, when to use which, the golden rule of rebasing, and safe commands for pull, conflicts and force-push.

By Published 8 min read
// CODE
Table of contents

git merge and git rebase both take the work from one branch and integrate it into another, and they produce the same final code. The difference is the history they leave behind. Merge joins two lines of development with a new merge commit and keeps every original commit untouched. Rebase replays your commits one by one on top of another branch, creating new commits and a straight-line history. The practical rule most teams follow: rebase your own unpublished work to keep it tidy, merge (or squash-merge) when bringing shared branches together, and never rebase commits other people already depend on.

This guide walks through what each command actually does, with commands you can run, and covers the settings and safety nets that keep rebasing from going wrong. If you haven't connected Git to your hosting provider yet, start with our guide to generating and using SSH keys.

The starting point: two branches that diverged

Imagine you branched feature/login off main, made two commits, and meanwhile a teammate added a commit to main:

          A---B   feature/login
         /
    o---o---C     main

Both branches now contain work the other lacks. You have two ways to bring feature/login up to date with main, or to land it on main.

How git merge works

A merge finds the common ancestor of the two branches, combines the changes since that point, and records the result as a new commit with two parents:

git switch feature/login
git merge main
          A---B---M   feature/login
         /       /
    o---o-------C     main

Commits A and B keep their original hashes. The merge commit M documents that the branches were joined, and when.

Fast-forward vs. merge commit

If the branch you're merging into hasn't moved since you branched, Git doesn't need a merge commit at all. It simply moves the branch pointer forward — a fast-forward. According to the merge options documentation, Git fast-forwards when it can and creates a merge commit only when it can't. Two flags change that:

# Always create a merge commit, even if a fast-forward is possible
git merge --no-ff feature/login

# Combine the branch's changes into the working tree and index,
# then make ONE ordinary commit yourself (no merge commit, no branch link)
git merge --squash feature/login
git commit -m "Add login form with input validation"

--no-ff is popular when you want each feature to appear as a visible unit in the history. --squash is what "squash and merge" buttons on hosting platforms do conceptually: the whole branch becomes a single commit on main.

Merge pros: non-destructive, safe on shared branches, preserves the true timeline. Cons: frequent "Merge branch 'main' into feature" commits can make git log hard to read.

How git rebase works

A rebase takes the patches introduced by your commits and reapplies them, in order, on top of a new base. The Pro Git book describes it as rewinding your branch to the target and replaying your work on top:

git switch feature/login
git rebase main
              A'--B'   feature/login
             /
    o---o---C          main

A' and B' contain the same changes as A and B, but they are new commits with new hashes, because their parent changed. Now main can be fast-forwarded to include the feature with no merge commit:

git switch main
git merge feature/login   # fast-forward

The final files are identical to the merge approach; only the shape of the history differs.

Rebase pros: a linear history that is easy to read, bisect and review. Cons: it rewrites commits, which causes real problems if anyone else has those commits.

The golden rule of rebasing

Pro Git boils the risk down to one rule: don't rebase commits that already exist outside your own repository if other people may have built work on top of them.

When you rebase, Git abandons the old commits and creates new ones. If a teammate already pulled the old ones and built on them, their history and yours now disagree, and the next pull produces duplicated commits and confusing conflicts. In practice:

  • Safe to rebase: local commits you haven't pushed; your own feature branch, even if pushed for a pull request, as long as nobody else is committing to it.
  • Don't rebase: main, develop, release branches, or any branch others pull from.

The book's suggested compromise is to rebase local changes to clean them up before pushing, but never rebase anything you've pushed somewhere others use.

Merge vs. rebase at a glance

git merge git rebase
History shape Branching, with merge commits Linear
Existing commits Unchanged Rewritten (new hashes)
Safe on shared branches Yes No
Conflicts Resolved once, in the merge commit May be resolved per replayed commit
Needs force-push afterwards No Yes, if the branch was already pushed
Best for Integrating shared/long-lived branches Updating and cleaning up private branches

Practical workflows and commands

Keep a feature branch up to date

git fetch origin
git switch feature/login
git rebase origin/main

Resolve conflicts during a rebase

Because rebase replays commits individually, it can stop at each one that conflicts. The git-rebase documentation provides these controls:

# fix the conflicted files, then:
git add path/to/file
git rebase --continue

git rebase --skip    # drop the commit that's being applied and move on
git rebase --abort   # give up and return the branch to where it started

If you hit the same conflict repeatedly, enabling git config --global rerere.enabled true tells Git to remember how you resolved a conflict and reuse that resolution.

Clean up commits with interactive rebase

Interactive mode opens a to-do list where each commit can be picked, reworded, edited, squashed or fixuped into the previous one, or dropped:

git rebase -i origin/main

A tidy habit is to create fix-up commits as you go and let Git place them automatically:

git commit --fixup=<commit-hash>
git rebase -i --autosquash origin/main

Setting rebase.autoSquash to true makes --autosquash the default for interactive rebases. If you work with stacked branches, --update-refs (or rebase.updateRefs=true) moves any other branches that point at the rebased commits so they don't get left behind.

Push a rebased branch safely

A rebased branch no longer descends from what's on the remote, so a normal push is rejected. Avoid plain --force, which overwrites whatever is there. Use a lease:

git push --force-with-lease --force-if-includes origin feature/login

Per the git-push documentation, --force-with-lease only overwrites the remote branch if it still matches your remote-tracking ref. The docs warn that background fetches (some editors run them) can silently update that ref and defeat the check; --force-if-includes closes that gap by also verifying that the remote tip is already part of your local branch's history. You can enable it by default with git config --global push.useForceIfIncludes true.

Fixing "You have divergent branches" on git pull

git pull is a fetch followed by an integration step. When both your local branch and its upstream have new commits, recent Git versions stop and print a hint asking how to reconcile them, listing three options:

git config pull.rebase false  # merge
git config pull.rebase true   # rebase
git config pull.ff only       # fast-forward only

Add --global to apply the choice everywhere. You can also decide per pull with git pull --rebase or git pull --no-rebase. For personal branches, pull.rebase true avoids noisy merge commits; pull.ff only is the most conservative, refusing to do anything except a fast-forward so you can choose deliberately each time. If you often pull with uncommitted changes, git config --global rebase.autoStash true stashes and reapplies them around the rebase — though the docs note the final reapply can still conflict.

How to undo a merge or rebase

Mistakes are recoverable because Git keeps a reflog of where each branch has pointed:

git reflog                       # find the commit before the operation
git reset --hard feature/login@{1}   # move the branch back one reflog step

--hard discards uncommitted changes, so commit or stash them first. For a merge you haven't pushed, git reset --hard ORIG_HEAD usually works too. For a merge that's already on a shared branch, don't rewrite history — use git revert -m 1 <merge-commit> to create a new commit that undoes it.

Which should you use?

A sensible default for most teams:

  1. Rebase your feature branch onto main while you work, and use interactive rebase to tidy commits before review.
  2. Merge the finished branch into main through a pull request — with a merge commit, a squash, or a rebase-and-merge, according to your team's convention.
  3. Never rebase shared branches, and force-push only with --force-with-lease.

Whatever you choose, consistency matters more than the choice itself — agree on it once and encode it in your repository settings and pull.rebase config. Just as a Python virtual environment keeps project dependencies predictable, a shared Git convention keeps your project history predictable for everyone who reads it later.

Frequently asked questions

+Is git rebase better than git merge?

Neither is better in general. Both end with the same code; they differ only in how history is recorded. Merge preserves exactly what happened, including when branches diverged. Rebase rewrites your commits to produce a linear history. Many teams rebase private feature branches and merge (or squash-merge) them into main.

+Can I rebase a branch I have already pushed?

Only if nobody else has based work on it, such as your own feature branch in a pull request. You will then need to force-push, and you should use git push --force-with-lease rather than --force. Never rebase shared branches like main.

+How do I undo a rebase?

During a rebase, run git rebase --abort to return to where you started. After it has finished, find the previous branch tip with git reflog (or the branch@{1} syntax) and reset to it, for example git reset --hard feature@{1}. Make sure you have no uncommitted work first.

+What does 'You have divergent branches and need to specify how to reconcile them' mean?

Your local branch and its upstream both have commits the other lacks, and Git wants you to choose a strategy. Run git pull --rebase or git pull --no-rebase once, or set pull.rebase (true or false) or pull.ff only in your Git config to make the choice permanent.

Sources & references

  1. Pro Git book — 3.6 Git Branching: Rebasing
  2. Git documentation — git-rebase
  3. Git documentation — merge options (--ff, --no-ff, --squash)
  4. Git documentation — git-push (--force-with-lease, --force-if-includes)
  5. Git source documentation — git-pull

Spotted an error? See our Corrections Policy.

  • #git
  • #version-control
  • #git-rebase
  • #git-merge
  • #developer-tools
KB

KernelBrief Editorial

The KernelBrief editorial desk researches, writes and fact-checks every article published on this site. Every article is checked against primary sources (official documentation, vendor announcements, standards bodies and original research) before publication. Every factual claim is linked to its source, and corrections are handled under our published Corrections Policy.