Rebasing

What rebase does, precisely

Rebase takes the commits that are unique to your branch, sets them aside as a list of patches, moves your branch's base to a new commit, and re-applies the patches one by one. After it finishes, your branch contains the same logical changes, but the commits themselves are new objects with new SHA-1 hashes. The originals become unreachable; they survive in the reflog for a while, then are garbage-collected.

That last detail is the whole story in one sentence: the same change, a different history. Two commits with identical patches are different commits if their parents differ, because a commit's hash is computed from its content, its parent, its author, and its timestamp. Change the parent and the hash changes with it. So replaying a commit onto a new base, even with no conflicts, always produces a new commit.

D and E are gone from the visible history. D' and E' carry the same patches but with C as the new parent of D'. The branch label feature moved to E'. As far as git log is concerned, your work now grows straight out of C, not B.

git rebase <upstream>

The everyday form has one argument:

git checkout feature
git fetch origin
git rebase origin/main

That tells Git: "Find the commits on feature that aren't on origin/main. Move my branch tip to origin/main. Replay those commits on top." If there are no conflicts, the rebase finishes silently. If there are, Git stops and asks you to resolve, then continue.

If you omit the second argument, the rebase operates on the current branch. git rebase <upstream> <branch> first checks out <branch>, then rebases it. The two-argument form saves a git checkout; otherwise it's identical.

Why people rebase — and why they don't

The pull toward rebase is straightforward: linear history is easier to read. git log --oneline shows a single sequence of commits. Each one applies cleanly on top of the previous. Bisect works without merge commits muddying the picture. A reviewer reading a feature branch sees a story, not a tangle.

The pull away from rebase is equally important: it rewrites history. The commits you had before the rebase no longer exist (visibly) in your branch. If you'd already pushed those commits, anyone who pulled them now has a divergent view of the world. When they re-fetch, Git sees their copy and your rewritten copy as two separate histories, and trying to merge them produces duplicates and confusion.

The golden rule

The rule in three lines:

• Local-only commits: rebase freely. They exist only in your repository; rewriting them costs no one anything.
• Pushed commits on a topic branch you alone use: rebase if you must, push with --force-with-lease (see below).
• Shared commits on a shared branch: don't rebase. Merge, or coordinate explicitly with everyone who has the commits.

Conflicts during a rebase

A rebase replays your commits one by one. Each replay is essentially a git cherry-pick, and any of them can hit a conflict. Resolution looks like the resolution you already know from merge conflicts: open the file, fix the conflict markers, stage the result. The difference is the verb you use to continue.

# rebase pauses on the offending commit
git status                # shows files with conflicts
$EDITOR src/parser.js     # fix the markers
git add src/parser.js     # stage the resolution
git rebase --continue     # replay the rest

# escape hatches:
git rebase --abort        # roll back to pre-rebase state
git rebase --skip         # drop this commit and continue

Three things to remember. First, --abort is always safe: Git records the pre-rebase tip in ORIG_HEAD, so aborting puts you exactly where you started. Second, you may need to resolve conflicts on more than one commit; the rebase will stop, you'll fix, continue, stop, fix, continue. Third, --skip drops the conflicting commit entirely; use it only when the commit is genuinely obsolete (e.g., already applied upstream).

Interactive rebase

The big-deal feature. Passing -i opens an editor with a list of the commits about to be replayed and a verb in front of each one. Change the verbs (or reorder the lines), save, exit, and Git carries out the script.

pick   2c0f7a1 Add parser scaffolding
reword 8e3b9d4 Add empty-input tests
squash 1a4d22e Fix typo in parser
fixup  9b772ce Another typo fix
drop   3d11ef0 Experimental: try regex engine

# Rebase d4e5f6a..3d11ef0 onto d4e5f6a (5 commands)
#
# Commands:
# p, pick   = use commit
# r, reword = use commit, but edit the commit message
# e, edit   = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup  = like "squash", but discard this commit's log message
# d, drop   = remove commit

The verbs do what they say. pick keeps the commit as-is. reword stops to let you rewrite the message. edit stops with the commit applied but unstaged, so you can amend the contents. squash merges the commit into the previous one and lets you compose a combined message. fixup is squash without the combined message — the previous commit's message wins. drop removes the commit. You can also reorder lines to rearrange commits, as long as the new order produces a buildable history at each step.

Interactive rebase is how you turn a stream of "wip", "fix again", "oops" commits into a clean, reviewable series before opening a pull request. It's the one tool that justifies committing imperfect work-in-progress: you can always reshape it later.

Autosquash workflow

When you spot a small fix that belongs in an earlier commit, you have two options. You can find the commit, run an interactive rebase, mark the right line as edit, amend, and continue. Or you can stage the fix and tell Git which commit it belongs to:

git add src/parser.js
git commit --fixup=8e3b9d4   # creates "fixup! Add empty-input tests"

That commit's message starts with fixup! followed by the subject of the target commit. Later, when you run an interactive rebase with --autosquash, Git automatically rearranges the todo list so each fixup sits right after its target with the fixup verb:

git rebase -i --autosquash <base>

You eyeball the todo list, save the editor, and the fixups disappear into their targets. The pattern lets you commit work-in-progress and amendments freely throughout a session, then collapse everything into clean commits in one move.

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

--onto: surgical rebases

The general form of rebase takes three arguments:

git rebase --onto <newbase> <oldbase> <branch>

This says: "Take the commits that are on <branch> but not on <oldbase>, and replay them on <newbase>." The everyday two-argument form git rebase <upstream> is the special case where <newbase> and <oldbase> are the same.

The classic use is moving a stack of commits to a different parent. Suppose you branched client off server, but you actually want those client commits to live on main instead. The commits unique to client (everything after server's tip) should land on main:

git rebase --onto main server client

Three arguments, three roles: the new home, the old base to subtract, and the branch to move. Read in order, the command translates to "onto main, take whatever's past server, in the branch client."

Pushing after a rebase

If a branch is rebased after it has been pushed, the next git push will be rejected. The remote's history and your local history have diverged — not in the additive way Git is used to, but because your local copy replaced commits the remote still holds. A normal push would have to overwrite the remote, and Git refuses without permission.

The first instinct is git push --force. Don't. --force overwrites the remote ref blindly, with no check that you have an up-to-date view of what's there. If a teammate pushed to the branch since you last fetched, their commits vanish. Use --force-with-lease instead:

git fetch origin                       # update remote-tracking refs
git rebase origin/main                 # rebase locally
git push --force-with-lease origin feature

If the push is rejected, do not retry with --force. Fetch, inspect what's new on the remote, decide whether to incorporate it, then push with --force-with-lease again. The check exists precisely so you can't lose someone else's work by accident.

Rebase vs merge

Both produce an integrated branch. They differ in what history records and how it reads later.

A workable team policy: rebase local feature commits onto an updated trunk before opening a PR (clean, focused, easy to review); merge when integrating long-lived branches or when the historical fact "this was a feature" is worth preserving. Many teams compromise with squash-merge on PR merge — the feature branch is developed however the author likes, then collapses into a single commit on the trunk.

Pull --rebase

By default, git pull fetches and then merges. If you've made local commits since your last fetch and the remote has moved, you get a merge commit on every pull. The history fills up with "Merge branch 'main' of origin/main" entries that record nothing meaningful.

Rebase fixes this. git pull --rebase fetches the remote, then rebases your local commits on top — as if you'd pulled before making your changes. The result is linear: upstream commits, then your work, no merge bubble. For the case where you're working alone on a branch (or you only have local commits ahead of the remote), this is almost always what you want. Set it as the default:

git config --global pull.rebase true

The same golden rule still applies: only your local commits get rebased, so the operation is safe by construction. The fetched upstream commits are untouched.

Common pitfalls

Worked examples

git checkout feature
git fetch origin
git rebase origin/main

# resolve any conflicts as they arise:
#   edit file, git add, git rebase --continue

# share the rebased branch (already pushed before):
git push --force-with-lease origin feature

a1b2c3d Add parser
e4f5g6h wip
i7j8k9l fix typo in parser
m0n1o2p Add parser tests

pick   a1b2c3d Add parser
fixup  e4f5g6h wip
fixup  i7j8k9l fix typo in parser
pick   m0n1o2p Add parser tests

git add src/parser.js
git commit --fixup=a1b2c3d

git rebase -i --autosquash origin/main

git rebase --onto main server client