Rebase: replay your work on a new base

The interactive lesson needs JavaScript. The text below is the complete lesson.

After this lesson you can

• explain why git rebase produces new commits with new IDs, and what happens to the originals understand
• use git rebase main to put a branch on top of main, then fast-forward main apply
• continue or abort a rebase that stops on a conflict apply
• choose between merge and rebase using the golden rule: rebase only private history, merge shared history evaluate

Understand: Same work, new parent

You work on feature and have made two commits, B and C. Meanwhile someone added D to main. The two lines have forked. You want your work to sit on top of the newest main.

You already know one answer: a merge. Git makes a merge commit M with two parents. Nothing is rewritten, and the graph shows honestly that the work happened in parallel.

Back to the fork: rebase takes another path. Git starts at the newest commit on main and replays your commits one at a time, as if you had written them there. The change from B becomes a new commit on top of D. If a change does not fit, Git stops.

When every commit has been replayed, Git moves the feature label to the last new commit. The history is now one straight line on top of D.

Look at the dashed commits. They are the originals, B and C, and they are unchanged. A commit's ID is computed from its snapshot, its parent, its message and its author. New parent, new ID. So rebase never moves commits. It makes copies and leaves the old ones behind.

To bring the work into main, you run git switch main and then git merge feature. Because feature is now directly ahead, it is a fast-forward. No merge commit, just a straight line.

Now the golden rule: never rebase commits that others already have. Suppose you had pushed the old feature. Then the originals live on at origin, and there are two versions of the same work. Rebase only private history, and merge when it is shared.

Watch: Put a feature branch on top of main

We are on feature. The graph shows the fork: two commits on feature and one new commit on main. Make a note of the IDs of the two feature commits.

$ git log --oneline --graph --all

Now the key command. git rebase main replays the commits from feature on top of main. Keep an eye on the IDs.

$ git rebase main

The graph is now a straight line, with new IDs on the feature commits. Git saved the old tip in ORIG_HEAD, and the log from there shows the originals, completely unchanged. If you regret the rebase, git reset --hard ORIG_HEAD takes you back.

$ git log --oneline -2 ORIG_HEAD

Now the work goes into main. First we switch to main.

$ git switch main

Merging feature is now a fast-forward. Git only moves the main label forward. Look for the word Fast-forward in the output.

$ git merge feature

The result is one straight line: first the snapshot, then the docs, then the two login commits.

$ git log --oneline --graph

Tasks

1. Show all branches as a graph, with one line per commit.
2. Replay feature on top of the newest main.
3. Bring main up to date with the work from feature, without a merge commit.

Watch: When a replay conflicts

Both branches changed the same line in README.md. We rebase greeting onto main. Git replays the commit, hits the conflict and stops halfway.

$ git rebase main

Let's look at the file. The markers are the same as in a merge conflict. But which side is called HEAD this time?

$ cat README.md

We resolve it like any conflict. We write the version we want, and mark it resolved with git add.

$ echo 'Welcome to Git class, friend!' > README.md && git add README.md

Now git rebase --continue makes the new commit and replays the rest. Git opens the commit message so you can adjust it. We keep it and save.

$ git rebase --continue

Tasks

1. Start replaying greeting on top of main.
2. Resolve the conflict by combining both lines, and mark the file as resolved.
3. Finish the rebase.

Practise: Transfer: a shop with three branches

You are on main. The branches docs, faq and pricing started before main moved on. faq is pushed, and Ada is building on it. The other two exist only on your machine. In the middle of a rebase, git rebase --abort puts everything back. No demo this time.

Tasks

1. Bring the work from docs into main as one straight line, with no merge commit.
2. Bring the FAQ from faq into main.
3. Rebase pricing onto main. It conflicts. You decide not to resolve it now. Back out, so that pricing is exactly as before.

Check yourself: Recall it

You pushed feature yesterday, and a classmate has built on it. Today main has moved on. What is the safe choice?

• Rebase feature onto main and force-push
• Merge, so the shared commits stay as they are
• Rebase, it is fine as long as you use git push --force-with-lease

During a rebase conflict you run git checkout --ours README.md. Which version do you get in the file?

• The version from your own commit, the one being replayed
• The version from the new base, with the commits already replayed
• The version from the common ancestor

Halfway through a rebase with conflicts you realise you started from the wrong branch. What puts everything back as it was before?

• git rebase --abort
• git rebase --skip
• git reset --hard

Review from “Branches and HEAD”: at the very end of a rebase, Git moves the branch feature. What does Git actually move?

• A copy of all the files on the branch
• A pointer to one commit, the tip of the branch
• A stored list of all the commits on the branch

Common misconceptions

• “Rebase moves my commits.” It makes new commits with new IDs. The originals stay unchanged until they are eventually cleaned up.
• “Rebase is always better because history looks cleaner.” Rewriting commits others already have leaves the team with duplicate versions and a lot of extra work.
• “In a rebase conflict, HEAD is my own change.” During a rebase HEAD stands on the new base, plus any commits already replayed. Your commit is the incoming side.

$ git rebase main
Successfully rebased and updated refs/heads/feature.
$ git log --oneline --graph --all
* d9c6470 Add login test
* d355c49 Add login form
* 6007fdb Add docs
* a5ea1be Initial snapshot
$ git reflog -5
d9c6470 HEAD@{0}: rebase (finish): returning to refs/heads/feature
d9c6470 HEAD@{1}: rebase (pick): Add login test
d355c49 HEAD@{2}: rebase (pick): Add login form
6007fdb HEAD@{3}: rebase (start): checkout main
0c10b5b HEAD@{4}: checkout: moving from main to feature
$ git rev-parse --short ORIG_HEAD
0c10b5b

$ git range-diff main ORIG_HEAD feature
1:  86eeba1 = 1:  d355c49 Add login form
2:  0c10b5b = 2:  d9c6470 Add login test

$ git log --oneline --graph --all
* 95dbcf3 Add student discount
* d3a55ee Show prices
| * 82af405 Add license
|/
* a5ea1be Initial snapshot
$ git rebase --onto main pricing discount
Successfully rebased and updated refs/heads/discount.
$ git log --oneline --graph --all
* 535e91d Add student discount
* 82af405 Add license
| * d3a55ee Show prices
|/
* a5ea1be Initial snapshot

$ git push --force-with-lease
 ! [rejected]        feature -> feature (stale info)

$ git fetch
$ git push --force-with-lease --force-if-includes
 ! [rejected]        feature -> feature (remote ref updated since checkout)