Himanshu SharmaSoftware engineer
Let’s talk

Git and GitHub · Lesson 13 of 30

Rebasing: replaying a branch onto a new base, and when not to

Use git rebase for a linear history, squash commits interactively, resolve rebase conflicts, and learn the golden rule about shared history.

15 minBranches and mergingUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonRebase a branch onto main, squash small commits together, continue or abort a rebase, and explain why you never rebase commits others already have.

What you can do after this lesson

You will understand rebase as a second way to combine work, use it to keep your own branch tidy, and know exactly where to stop. Rebase has a reputation for being dangerous. The danger is real but narrow, and it comes down to a single rule you will see below.

Merge versus rebase

Both commands integrate changes from one branch into another, and they differ in how history looks afterwards.

A merge ties two lines together with a merge commit. Nothing is rewritten.

A rebase takes your branch's commits, sets them aside, moves the branch to the new starting point (usually the tip of main), and replays your commits one by one on top. The commits are recreated, so they get new hashes. History looks as if you had started your work from the latest main all along.

A first rebase

The setup is a fictional repository. topic was branched from commit A and has two commits, T1 and T2. Meanwhile main gained commit B:

bash
git log --oneline --graph --all
text
* 6ae04f8 B: main moves on
| * 2bc7870 T2: more topic work
| * f74211c T1: topic work
|/  
* 110bb67 A: first

(Hashes here are from a practice run; yours will differ.) Switch to topic and rebase it onto main:

bash
git switch topic
git rebase main
git log --oneline --graph --all
text
Rebasing (1/2)Rebasing (2/2)Successfully rebased and updated refs/heads/topic.
* de29a55 T2: more topic work
* 366d68b T1: topic work
* 6ae04f8 B: main moves on
* 110bb67 A: first

Compare the hashes: T1 was f74211c and is now 366d68b. Same changes and messages, but new commits sitting on a new parent. The history is a straight line. Now main can fast-forward to the tip of topic:

bash
git switch main
git merge topic
text
Updating 6ae04f8..de29a55
Fast-forward
 t1.txt | 1 +
 t2.txt | 1 +
 2 files changed, 2 insertions(+)
 create mode 100644 t1.txt
 create mode 100644 t2.txt

No merge commit appears, and the log is one clean line. That tidy history is the reason teams like rebase.

When a rebase hits a conflict

Rebase replays commits one at a time, so a conflict stops it on the commit that clashes. Say main made a theme green while your branch made it blue:

bash
git rebase main
text
Rebasing (1/1)Auto-merging theme.txt
CONFLICT (content): Merge conflict in theme.txt
error: could not apply 679bead... Make it blue
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".

(The full output has more hint lines; they were trimmed here.) The file has the same markers as in the merge lesson. Edit it to the final text, then:

bash
git add theme.txt
git rebase --continue
text
[detached HEAD 33efdc5] Make it blue
 1 file changed, 1 insertion(+), 1 deletion(-)
Successfully rebased and updated refs/heads/blue.

If the rebase has several commits, you may have to repeat this for each. To abandon it, git rebase --abort returns the branch exactly as it was, and git rebase --skip drops the commit being applied. Note the different feel from merge: you resolve conflicts once per replayed commit, rather than once overall.

Interactive rebase: tidying your own commits

git rebase -i HEAD~3 opens an editor listing the last three commits, each marked pick. Change the word to rewrite them:

  • reword changes a message.
  • squash melds a commit into the one above it, combining messages.
  • fixup does the same but discards the message.
  • drop removes a commit.
  • Reordering lines reorders commits.

The editor is interactive, so in our practice run we scripted the edit. From this history of messy small commits:

text
250a9ab fix typo again
d01ba2b fix typo
e1c8bf3 Add feature
dc8c2b0 Base

squashing the two typo fixes into Add feature gave:

text
c808180 Add feature
dc8c2b0 Base

Before sharing, this is a good way to turn "wip", "oops" and "fix typo" into one commit per idea. If you create fix-up commits as you go with git commit --fixup <commit>, then git rebase -i --autosquash arranges and squashes them for you. In our test, a fixup for Add a was moved next to it and absorbed, so the log ended with Add a, Add b and Add c and no leftover fixup commit.

The golden rule

Never rebase commits that other people have already pulled. Rebase creates replacements, and the old commits are abandoned. If a teammate has the old ones, their history and yours now disagree, and sorting that out is painful. Rebase your private, local work freely. Once a branch is pushed and shared, prefer merge or revert. If you rebase a branch you pushed for yourself, for example your own pull request branch, you must push again with --force-with-lease (see the remotes lesson), which is acceptable only if you are sure nobody else builds on it.

Common mistakes

  • Rebasing a shared branch such as main. Do not.
  • Rebasing in the wrong direction. git rebase main run on topic moves topic. Run on main it does something different from what you intended.
  • Fixing the same conflict repeatedly. If many commits clash, aborting and merging instead is a reasonable choice.
  • Forgetting that hashes change. Do not paste old hashes into discussions after a rebase.
  • Force pushing with plain --force. Prefer --force-with-lease.

Exercise

  1. Create topic with two commits and add a different commit to main.
  2. Rebase topic onto main and compare the log before and after.
  3. Make three tiny commits on topic and squash them into one with git rebase -i.
  4. Provoke and abort a rebase conflict.
Show one possible answer
bash
git switch topic
git rebase main
git log --oneline --graph --all
git rebase -i HEAD~3

In the editor, leave the first line as pick and change the next two to squash. Save, then write a single message. To practise the abort, change the same line differently on both branches, run git rebase main, then git rebase --abort.

Next: Remotes: clone, fetch, pull and push.

Key points

  • git rebase main takes the commits unique to your branch and replays them on top of main, creating new commits with new hashes.
  • The result is a straight-line history, often followed by a fast-forward merge.
  • Interactive rebase (git rebase -i) lets you squash, reword, reorder or drop your own commits.
  • Conflicts during a rebase are resolved commit by commit, then git rebase --continue; git rebase --abort goes back.
  • Golden rule: never rebase commits that other people already have, because it rewrites history they depend on.

Check yourself

1. What does git rebase main do from a feature branch?
2. Why do rebased commits have different hashes?
3. When should you NOT rebase?
4. You are in the middle of a rebase that went badly. Which command returns the branch to how it was?