Lesson 06 intermediate

Git Rebasing

What git rebase does to commits, rebase versus merge, keeping a feature branch up to date, cleaning commits with interactive rebase, fixup commits and autosquash, stacked branches with --update-refs, handling conflicts and the golden rule of never rebasing shared history.

Rebasing is the other way to integrate work. Instead of joining two lines of history with a merge commit, it replays your commits on top of another branch as if you had started your work from there. The result is a straight, easy-to-read history. The price is that rebasing creates new commits, so it needs one rule that this lesson explains.

What rebase does

Your branch feature/search started from commit 5d1e. Since then, main got two new commits:

          c42d <- e71b          (feature/search)
         /
  5d1e <- 7aa0 <- 90bd          (main)

Running git rebase main on the feature branch takes your commits, sets them aside, moves the branch to the tip of main and applies them again one by one:

  5d1e <- 7aa0 <- 90bd <- c42d' <- e71b'   (feature/search)
                    |
                  (main)
$ git switch feature/search
$ git rebase main
Successfully rebased and updated refs/heads/feature/search.

The commits c42d' and e71b' have the same changes and messages as before but new IDs, because their parent changed. The old commits still exist for a while (the reflog remembers them) but no branch points to them.

Now main can fast-forward to the feature branch, and history stays a straight line.

Rebase or merge?

MergeRebase
HistoryTrue record, with merge commitsStraight line, as if work happened in order
CommitsUntouchedRewritten with new IDs
Safe on shared branchesYesNo, only on your own commits
ConflictsResolved once, in the mergePossibly once per replayed commit
Best forIntegrating finished work into mainUpdating your branch and tidying it before review

A common team rule combines both: rebase your own feature branch to keep it current and clean, then merge it into main through a pull request.

The golden rule

Never rebase commits that other people have already based work on. Rebasing replaces commits with new ones. If a teammate built on the old ones, their history and yours now disagree, and sorting that out is painful.

In practice: rebase freely on a branch only you use, or before you push. After rebasing a branch you had already pushed, a normal push is rejected because the remote history no longer matches. Push with:

$ git push --force-with-lease

--force-with-lease overwrites the remote branch only if it still points where you last saw it. If a teammate pushed in the meantime, the push fails instead of silently deleting their work. Never use plain --force on a shared branch.

Keeping a branch up to date

While you work on a feature, main keeps moving. Bring those changes in regularly so the final merge stays small:

$ git fetch origin
$ git rebase origin/main

Or make git pull rebase instead of merge for one pull, or for good:

$ git pull --rebase
$ git config --global pull.rebase true

Interactive rebase: tidy up before review

git rebase -i lets you edit a series of commits before others see them. Your branch has four commits, and two of them are “oops” commits:

$ git log --oneline main..
f1a9e20 fix typo
b7d3c11 Add date ranking to search
0e5c8a7 wip
c42d9e1 Add search endpoint
$ git rebase -i main

Git opens your editor with one line per commit, oldest first:

pick c42d9e1 Add search endpoint
pick 0e5c8a7 wip
pick b7d3c11 Add date ranking to search
pick f1a9e20 fix typo

Change the words at the start of each line to say what should happen, then save and close:

pick c42d9e1 Add search endpoint
fixup 0e5c8a7 wip
pick b7d3c11 Add date ranking to search
fixup f1a9e20 fix typo
CommandEffect
pickKeep the commit as is
rewordKeep the changes, edit the message
editStop at this commit so you can change it or split it
squashCombine with the previous commit and merge both messages
fixupCombine with the previous commit and drop this message
dropRemove the commit entirely

You can also reorder lines to reorder commits. The branch now has two clean commits, ready for review.

Fixup commits and autosquash

Often you notice a mistake in an earlier commit while working on a later one. Instead of rebasing right away, record a fix that says which commit it belongs to:

$ git add search.js
$ git commit --fixup c42d9e1
[feature/search 77a0d3e] fixup! Add search endpoint
$ git rebase -i --autosquash main

With --autosquash, the editor opens with the fixup! commit already moved under its target and marked fixup. Set rebase.autoSquash true to make this the default. For a single quick fix to an older commit, Git 2.55’s experimental git history fixup does the same without a rebase at all (lesson 9).

Handling conflicts during a rebase

Because commits are applied one at a time, a rebase can stop on any of them:

$ git rebase main
CONFLICT (content): Merge conflict in server.js
error: could not apply b7d3c11... Add date ranking to search

Resolve the file exactly as in lesson 5, then:

$ git add server.js
$ git rebase --continue      # apply the remaining commits
$ git rebase --skip          # or drop this commit and go on
$ git rebase --abort         # or give up and restore the branch as it was

During a rebase, --ours means the branch you are rebasing onto and --theirs means your commit being replayed. It is the opposite of a merge, and it confuses everyone at least once.

More useful options

  • git rebase --onto main old-base feature moves only the commits after old-base onto main. Useful when your branch was based on another feature branch that has since been merged.
  • git rebase -i --update-refs main (Git 2.38) also moves any other branches that point into the rebased commits. If you work with stacked branches, one small pull request built on another, every branch in the stack moves along.
  • git rebase --exec "npm test" main runs a command after each replayed commit and stops if it fails, so every commit in the result passes the tests.
  • git rebase --trailer "Reviewed-by: Ana Souza <ana@orbit.dev>" main (Git 2.54) adds a trailer line to every rebased commit message.

Quick reference

TaskCommand
Replay your branch on top of maingit rebase main
Update from the remote with rebasegit pull --rebase
Edit, squash, reorder commitsgit rebase -i main
Record a fix for an earlier commitgit commit --fixup <commit>
Apply the fixupsgit rebase -i --autosquash main
After a conflictgit rebase --continue / --skip / --abort
Move a stack of branchesgit rebase -i --update-refs main
Push a rebased branch safelygit push --force-with-lease

Exercise

Your feature branch has five commits and main moved ahead. You run git rebase main. What happens to your five commits?

  1. They are merged into a single merge commit
  2. They keep their IDs and move to the top of main
  3. They are replayed on top of main as new commits with new IDs
  4. They are deleted and replaced by main’s commits
Show answer

Answer: C. Rebase re-applies each of your commits on a new base. The changes and messages stay the same, but the parent changes, so every commit gets a new ID.

Exercise

You rebased a branch you had already pushed, and git push is rejected. The branch is yours alone, but you want to be safe in case someone did push to it. What do you run?

  1. git push –force
  2. git pull, then git push
  3. git push –no-verify
  4. git push –force-with-lease
Show answer

Answer: D. –force-with-lease overwrites the remote branch only if it is still where you last fetched it. If somebody pushed meanwhile, it refuses instead of throwing their commits away. Pulling would merge the old commits back in.

Exercise

In git rebase -i you want to fold a “fix typo” commit into the commit just above it and throw away its message. Which command do you write on its line?

  1. fixup
  2. squash
  3. drop
  4. edit
Show answer

Answer: A. fixup combines the commit with the previous one and discards its message. squash also combines them but asks you to edit a message made of both. drop would lose the typo fix entirely.

Key takeaways

  • Rebase replays your commits on a new base, giving a straight history and new commit IDs.
  • Never rebase commits others have built on; after rebasing your own pushed branch, use --force-with-lease.
  • git rebase -i rewords, squashes, reorders and drops commits before review.
  • git commit --fixup plus --autosquash is the clean way to fix earlier commits.
  • On conflicts: resolve, git add, git rebase --continue, or --abort to start over.

FAQ

Is rebasing dangerous?

Only for shared history. On your own branch it is safe, and even a bad rebase can be undone: git reflog shows where the branch was before, and git reset --hard <that commit> brings it back (lesson 9).

Should I rebase or merge main into my feature branch?

Both work. Rebasing keeps your branch’s history clean and the final pull request easy to read. Merging main into the branch is safer if several people push to it. Follow your team’s convention.

Why do I have to resolve the same conflict several times during a rebase?

Each of your commits is applied separately, so a conflict in a line you changed in several commits appears once per commit. Squash related commits first, or enable rerere so Git reuses your resolution.

What does git pull –rebase change?

Instead of creating a merge commit when your local branch and the remote both have new commits, it replays your local commits on top of the remote ones. Your history stays linear, and there are no “Merge branch main of origin” commits.

Can I rebase a branch that contains merge commits?

By default, rebase flattens merges and drops the merge commits. Use --rebase-merges to keep the branch structure. The newer git history command refuses to work on histories with merges.

↑ ↓ navigate Enter open Esc close