Git rebase branch: how to rebase safely, step by step

To rebase a branch, fetch, switch to it and replay it onto the new base: `git fetch origin`, `git switch topic`, `git rebase origin/main`. Git sets your branch’s own commits aside, moves the branch to the tip of origin/main, then reapplies the commits one at a time. The history stays a straight line with no merge commit. Every replayed commit gets a new hash, so a branch you already pushed needs git push --force-with-lease afterwards.

What does git rebase do to a branch?

Say topic has two commits of its own, and main has gained three since the branch started. Rebasing updates that starting point without merging main into your branch:

# before
A---B---C---D---E   origin/main
     \
      F---G         topic

# after git rebase origin/main
A---B---C---D---E   origin/main
                 \
                  F'---G'   topic

F' and G' hold the same changes and messages as F and G, but they are new commits with new hashes, because their parents changed. A merge from the same starting point would keep both lines and add one commit with two parents. The lesson on merge versus rebase shows both on one graph.

How do I rebase a branch safely, step by step?

Inspect first, keep the old tip, replay, then test. The first three commands rewrite nothing:

# 1. update origin/main, your files stay as they are
git fetch origin

# 2. list the commits Git will replay
git log --oneline origin/main..topic

# 3. keep a name on the old tip
git branch topic-backup topic

# 4. replay
git switch topic
git rebase origin/main

Stop at step 2 if the list has a commit you do not recognise, because it means the branch did not start where you thought. When the rebase ends, run git status to confirm it finished, then run your tests. A rebase with no conflicts can still break behaviour.

Name the base every time. A bare git rebase uses the branch’s upstream, which is often origin/topic and not main. To move a branch that started from another feature branch, name the old base too: git rebase --onto main old-base topic. The lesson on rebasing unpublished work practises this on a real graph.

How do I fix conflicts during a rebase?

Git applies your commits one at a time, so it can stop more than once, even in the same lines. Fix only the commit Git stopped on, since the later ones have not been applied yet:

# edit the file and remove the conflict markers, then
git add path/to/file
git rebase --continue

If you replay the same conflict often, git config rerere.enabled true records your resolution and reuses it. Check each reused result, because yesterday’s answer can be wrong in today’s code. The lesson on continue, skip and abort goes through each case, and how to resolve merge conflicts covers reading the markers.

How do I check a rebase before pushing?

Compare the old series with the new one before anyone else sees it:

# old and new commits, matched pair by pair
git range-diff origin/main topic-backup topic

# everything the branch adds to main, as one diff
git diff origin/main...topic

# the shape of the history
git log --graph --oneline --decorate origin/main topic

git range-diff shows when a conflict resolution changed a patch, or when a commit went missing. Code that compiles can still hide a dropped test or a changed condition, and this is where you catch it.

How do I undo a rebase?

While it is running, use git rebase --abort. Once it has finished, move the branch back to the old tip. Check git status first, because --hard discards uncommitted changes:

git reset --hard topic-backup

# no backup? find the old tip in the reflog
git reflog show topic
git reset --hard <old-tip-hash>

The guide to undoing a reset, rebase or commit covers the reflog in more depth.

How do I push a rebased branch?

A normal push is refused, because the remote branch still holds the old commits and Git sees a non-fast-forward update. Check what you are about to replace, then push with a lease:

git fetch origin
git log --oneline topic..origin/topic
git push --force-with-lease origin topic

That git log should list only your old commits. Anything else is a teammate’s work, so stop and bring it in first. --force-with-lease replaces the remote branch only if it is still where your last fetch saw it, and plain --force has no such check. Background fetches update that value, so scripts can name the commit they expect: git push --force-with-lease=topic:<expected-hash> origin topic.

Should I rebase or merge this branch?

The guide to rebasing a branch has every option, and force push with lease covers the push. To squash, reword or reorder along the way, read interactive rebase in a GUI.