Skip to content
Velloreth
Developer Tools 5 min read

Git Merge vs Rebase: When to Use Each

Merge preserves history, rebase rewrites it. Learn the difference, the golden rule, and how to choose for your workflow.

By

What merge does

Merge combines two branches and creates a merge commit that has two parents.

git checkout main
git merge feature
main     ──●──●──────────●──►
              \        /
feature        ●──●──●

The merge commit records that the branches diverged and were joined. The full history is preserved, including the shape of the branch.

Advantages:

  • Non-destructive. No existing commit changes.
  • Preserves the true history, including when work happened in parallel.
  • Safe on shared branches.

Disadvantages:

  • The history is not linear, which makes it harder to read with git log.
  • A merge commit for every integration adds noise.

What rebase does

Rebase replays commits onto a new base, as if they had been made there.

git checkout feature
git rebase main
Before:
main     ──●──●
              \
feature        ●──●──●

After:
main     ──●──●
                \
feature          ●'──●'──●'

The commits are recreated with new hashes. The original commits are abandoned.

Advantages:

  • Linear history, which is easier to read.
  • No merge commits.
  • A clean sequence of commits on top of the latest main.

Disadvantages:

  • Rewrites history, which breaks anyone who has the old commits.
  • Conflicts may need resolving more than once, because each commit is replayed.
  • Loses the record of when the branch diverged.

The golden rule

Never rebase commits that have been pushed to a shared branch.

Rebasing rewrites commit hashes. If someone else has the old commits, their history and yours diverge. Their next push is rejected, and if they force-push, they may reintroduce the old commits and undo your work.

The rule in practice:

  • Safe to rebase: your local commits that nobody else has.
  • Unsafe to rebase: anything on main, develop, or a branch someone else is working on.

If you must rebase a shared branch, coordinate with everyone who has it, and tell them to reset to the new history rather than merge.

Recovering from a bad rebase

The reflog records every position of HEAD.

git reflog
# a1b2c3d HEAD@{0}: rebase (finish): returning to refs/heads/feature
# e4f5g6h HEAD@{1}: rebase (start): checkout main
# i7j8k9l HEAD@{2}: commit: add validation

Find the commit before the rebase and reset to it.

git reset --hard i7j8k9l

The reflog keeps entries for a period (90 days by default for reachable commits), so a rebase is recoverable if you act reasonably soon.

Interactive rebase

The most useful form of rebase is interactive, which lets you edit the commit sequence.

git rebase -i HEAD~3

This opens an editor with the last three commits.

pick a1b2c3d Add user model
pick e4f5g6h Fix typo
pick i7j8k9l Add validation

The commands:

  • pick — keep the commit.
  • reword — keep the changes, edit the message.
  • edit — stop to amend the commit.
  • squash — combine with the previous commit, keeping both messages.
  • fixup — combine with the previous commit, discarding this message.
  • drop — remove the commit.
  • exec — run a shell command.

Reordering the lines reorders the commits.

This is how you clean up a messy local branch before pushing: squash the “fix typo” commits into the commit they fix, reword the messages, and drop the debugging commits.

Squash merging

A squash merge combines all the commits on a branch into one commit on the target.

git checkout main
git merge --squash feature
git commit -m "Add user authentication"

Or, on GitHub, the “Squash and merge” button.

Why it is useful. It keeps main linear without rewriting shared history. The branch’s individual commits are discarded, and one clean commit lands on main.

The cost. The individual commits are lost from main’s history. If you need to bisect to find which change introduced a bug, you only have the squashed commit, not the individual steps.

When to use it. A feature branch with many small commits, where the individual steps are not interesting. This is the most common merge strategy on GitHub.

Pulling

git pull is fetch plus merge. It creates a merge commit when the local and remote branches have diverged.

git pull

git pull --rebase is fetch plus rebase. It replays your local commits on top of the remote.

git pull --rebase

The rebase version avoids a merge commit for every pull, which keeps the history linear. Many teams set it as the default.

git config --global pull.rebase true

Choosing

Use rebase when:

  • Cleaning up local commits before pushing.
  • Updating a feature branch with the latest main.
  • You want a linear history and nobody else has the branch.

Use merge when:

  • Integrating a shared branch.
  • You want to preserve the true history.
  • The branch has been pushed and others may have it.

Use squash merge when:

  • The branch has many small commits.
  • You want main linear without rewriting shared history.
  • The individual commits are not interesting.

A common workflow combines all three: rebase locally to clean up, push, open a pull request, and squash merge into main.

Practical guidance

  • Never rebase a shared branch.
  • Rebase local commits to clean them up before pushing.
  • Use git pull --rebase to avoid merge commits on every pull.
  • Use interactive rebase to squash and reword.
  • Use squash merge to keep main linear.
  • Use git reflog to recover from a bad rebase.
  • Resolve conflicts once with rebase, or once per merge with merge.
  • Agree as a team on one strategy.

For the related guides, see git-branching-strategies and git-commit-messages-guide. For the broader context, git-undo-changes-guide and git-aliases-and-config.

Quotable summary

Merge creates a merge commit and preserves the full history, including when branches diverged, while rebase replays commits onto a new base, producing a linear history but rewriting commit hashes. The golden rule is never to rebase commits that have been pushed to a shared branch, because rewriting hashes diverges everyone else’s history and their next push will be rejected. Use rebase to clean up local commits before pushing and to update a feature branch, and merge to integrate shared branches. Squash merging combines a branch’s commits into one, which keeps main linear without rewriting shared history, at the cost of losing the individual commits from main’s history. A bad rebase is recoverable with git reflog.

Frequently asked questions

What is the golden rule of rebasing?
Never rebase commits that exist on a shared branch. Rebasing rewrites commit hashes, so anyone who has those commits will have a diverged history, and their next push will be rejected or will reintroduce the old commits.
Does rebase lose history?
It loses the record of when a branch diverged and merged, because it replays the commits as if they were made on the new base. The individual commits survive, but their hashes and timestamps change.
What is a squash merge?
It combines all the commits on a branch into a single commit on the target branch. The branch's individual commits are not preserved in the target's history, which keeps main linear and readable.
How do I undo a rebase?
Use git reflog to find the commit before the rebase, then reset to it. The reflog records every position of HEAD, so the pre-rebase state is recoverable for a period.
Should I merge or rebase when pulling?
Use git pull --rebase to replay your local commits on top of the remote, which avoids a merge commit for every pull. Use a plain pull when you want the merge commit to record the integration.
What is a fast-forward merge?
It happens when the target branch has no new commits, so Git can simply move the pointer forward without creating a merge commit. The history stays linear.