Playbook
Home / Git & GitHub / Sync with remote

Rebase or merge? Which one should I use

careful advanced #rebase#merge#history

When to use this: You have seen both words and are not sure which to use to bring in new commits.

Be careful with this one. Rebase rewrites your commits. Never rebase commits you have already pushed and shared.

Before you start

Steps

  1. Merge: keep history as it happened

    terminal
    git merge main

    Adds one merge commit. Existing commits are untouched, so it is always safe to push afterwards.

  2. Rebase: replay my commits on top of main

    terminal
    git rebase main

    Takes your branch's commits, moves the branch tip to main, and re-applies your commits one by one. Result: a straight line, but every commit gets a new ID.

  3. Give up on a rebase that went wrong

    terminal
    git rebase --abort

    Returns the branch to exactly how it was before you started.

  4. After a rebase of an already-pushed branch

    terminal
    git push --force-with-lease

    Pushed history changed, so a normal push is rejected. --force-with-lease overwrites only if nobody else pushed to it since you last fetched. Only for your own branches, never main.

How to verify it worked

  • git log --oneline --graph shows the history shape you wanted.

How to undo it

Rebased and regret it? The old state is still in the reflog:

terminal
git reflog
git reset --hard "HEAD@{N}"

Common errors and fixes

Conflicts during every step of a rebase A rebase replays each commit, so you may resolve conflicts repeatedly. Fix, git add, git rebase --continue. If it is a mess, git rebase --abort and use merge.

Q&A

One-line rule for rebase vs merge?

Rebase your own local, unpushed work to tidy it. Merge when other people (or Vercel previews, PRs) already depend on the branch.

Why is force-pushing dangerous?

It replaces the remote history. Teammates' commits can be erased and their clones break. --force-with-lease reduces, but does not remove, the risk.

Practice these as flashcards →

Terms in this scenario

MergeRebaseForce push

Related scenarios

My notes

Saved in this browser only.