Git Rebase Cheat Sheet

Rebase onto main or master

Run rebase from the branch you want to move. It replays that branch's commits on top of the target.

The full update loop, step by step:

git switch feature
git fetch origin
git rebase origin/main        # if it stops on a conflict: fix, git add, git rebase --continue
git push --force-with-lease   # the commits were rewritten, so a plain push is rejected

Rebase After a Pull

When your branch and its remote have both moved, Git stops with "You have divergent branches and need to specify how to reconcile them". Rebasing puts your local commits back on top instead of making a merge commit.

# hint: You have divergent branches and need to specify how to reconcile them.
git config --global pull.rebase true   # set it once
git pull                               # now rebases instead of merging

After someone squash-merges your pull request, the branch's old commits no longer match anything upstream, so a plain rebase replays them as duplicates. Move only the commits you added since then:

git rebase --onto origin/main <last-commit-that-got-squashed> feature

Interactive Rebase

git rebase -i opens a todo list of commits, oldest first. Change the word in front of a commit to change what happens to it; reorder the lines to reorder the commits.

A typical cleanup todo before opening a pull request:

pick a1b2c3d Add login endpoint
fixup e4f5a6b fix typo
reword 7c8d9e0 Add rate limiting
drop f0a1b2c WIP

Rebase Editor

The todo list opens in your sequence editor, which defaults to core.editor and then to vim. Saving an empty todo, or quitting with an error, cancels the rebase.

--wait is not optional for a GUI editor. Without it the command returns immediately, Git sees an unchanged todo, and the rebase runs before you have edited anything.

Fixup, Squash & Reword

Mark a commit as a fix the moment you make it, and --autosquash files it under its target in the todo for you.

# Fix a typo that lives three commits back
git add src/auth.js
git commit --fixup=abc1234
git rebase -i --autosquash main   # the fixup line is already in place; save and quit

Squash Commits

To squash the last N commits into one, rebase over them interactively and keep only the first pick.

git rebase -i HEAD~3

pick a1b2c3d Add password reset
fixup e4f5a6b fix failing test
fixup 7c8d9e0 review feedback

The reset route gets the same result without touching the rebase machinery:

git reset --soft HEAD~3
git commit -m "Add password reset"

With Conflicts

A rebase replays commits one at a time, so it can stop on any of them. Fix the files, stage them, continue. Never run git commit yourself mid-rebase; --continue commits for you.

The whole loop:

git rebase main
# CONFLICT (content): Merge conflict in src/app.js
vim src/app.js                # remove the <<<<<<< ======= >>>>>>> markers
git add src/app.js
git rebase --continue         # repeat until "Successfully rebased"

Abort, Continue, Skip

--continue after staging fixes, --skip when the commit is already upstream, --abort when the whole thing went sideways.

If --continue says there is nothing to commit, the resolution made the commit empty, usually because the change already exists upstream. That is what --skip is for.

Ours vs Theirs

During a rebase, ours and theirs are the reverse of what most people expect. Rebase checks out the branch you are rebasing onto and replays your commits against it, so --ours is that base branch (main) and --theirs is your own commit.

Editors rename the same two sides. In VS Code's conflict view during a rebase, "Current Change" is the base branch and "Incoming Change" is the commit of yours being replayed.

After a --ours/--theirs checkout, the file still needs git add and git rebase --continue.

# Keep your version of the lock file for every conflict in this rebase
git rebase -X theirs main

# Or decide per file, mid-conflict
git checkout --theirs -- package-lock.json
git add package-lock.json
git rebase --continue

Rebase --onto

--onto moves a range of commits to a new base: git rebase --onto <new-base> <old-base> <branch>. Read it as "take the commits after old-base up to branch, and replay them on new-base".

# You branched featureB off featureA, and featureA just merged.
# Replay only featureB's own commits onto main:
git rebase --onto main featureA featureB

Edit a Commit

Mark a commit edit in the todo and the rebase stops right after applying it, with the commit as HEAD.

# Change a file inside an older commit
git rebase -i abc1234^        # change "pick abc1234" to "edit abc1234"
vim src/config.js
git add src/config.js
git commit --amend --no-edit
git rebase --continue

To split it instead: git reset HEAD^ at the stop, then stage and commit the pieces separately before --continue.

Exec

exec runs a command after a commit is applied and stops the rebase if it fails, which pinpoints the commit that broke things.

# Find the commit that broke the tests while rebasing a branch
git rebase -x "npm test" main
# stops at the first failing commit: fix it, git commit --amend, git rebase --continue

Rebase vs Merge

Both integrate one branch into another; they leave different history behind.

Rule of thumb: rebase your own feature branch to keep it current, merge to land finished work into a branch other people use. The git cheat sheet covers the merge side in full.

Rebase on GitHub

GitHub's "Rebase and merge" button replays a pull request's commits onto the base branch with no merge commit, rewriting them with new SHAs. Both it and the "Update branch" dropdown need a clean replay; on a conflict you do it locally and push.

# "This branch is out-of-date with the base branch" on a PR with conflicts
git fetch origin
git rebase origin/main        # fix, git add, git rebase --continue
git push --force-with-lease   # the PR updates in place, review comments stay

Force-pushing a rebased branch keeps the pull request and its conversation; only the diffs of individual commits become unreachable, so old review comments may show as outdated.

Cherry-pick vs Rebase

cherry-pick copies commits and leaves the originals alone, so the change exists in two places. Rebase moves a range onto a new base and abandons the originals. See the git cheat sheet for the rest of cherry-pick.

# One fix belongs on the release branch too: copy it
git switch release-2.1
git cherry-pick abc1234

# The whole branch started from the wrong base: move it
git rebase --onto main old-base feature

Undo a Rebase

The old commits are not gone after a rebase; the reflog still points at them for about 90 days.

git reflog
# a1b2c3d HEAD@{0}: rebase (finish): returning to refs/heads/feature
# ...
# 9f8e7d6 HEAD@{7}: commit: the tip before the rebase started
git reset --hard HEAD@{7}

Pick the entry just below the first rebase (start) line: that was the branch tip before anything was rewritten.

Gotchas

• Never rebase commits other people have already pulled. Rewriting a shared branch forces everyone else into a painful recovery; merge on shared branches, rebase on your own.
• After any rebase, a plain git push is rejected. Use git push --force-with-lease, never bare --force: with-lease fails safely if a teammate pushed in the meantime.
• Ours and theirs swap meaning during a rebase. --ours is the branch you are rebasing onto, --theirs is your own commit. -X ours and -X theirs swap the same way.
• Do not git commit after fixing a conflict; git add then git rebase --continue is the whole move. Committing by hand mid-rebase leads to duplicated or empty commits.
• Rebase refuses to start over uncommitted changes. Commit them, stash them, or pass --autostash (or set rebase.autostash true once).