What Is Git Rebase? When to Use It and When Not To
Git rebase replays your commits on a new starting point. Here is how it works, the one rule about shared branches, and how to recover when it goes wrong.
Git rebase takes a series of commits and replays them on top of a different starting point. If your branch forked from main last week and main has moved on, rebasing your branch onto main rewrites your commits so they appear to start from main's current tip. The result is a straight line of history instead of a fork and a join.
What rebase does
The Git manual page for rebase uses a simple picture. A topic branch diverged from master at commit E. Running git rebase master on the topic replays its commits A, B and C on top of master's current tip, producing new commits A', B' and C'. The same command can reorder or combine commits through interactive mode.
The word "new" matters. Each replayed commit gets a different ID, because its parent changed. The old commits still exist for a while, they are just no longer on your branch.
git switch my-feature
git rebase mainRebase versus merge
Both bring your work and the latest main together. They differ in the history they leave behind.
Merge | Rebase | |
|---|---|---|
Result | A merge commit joins two lines | One straight line |
Commit IDs | Unchanged | Rewritten |
Conflicts | Resolved once | Resolved per replayed commit, as needed |
Safe on a shared branch | Yes | No |
If you are new to branches, start with what a git branch is.
The one rule
The manual is blunt: rebasing a branch that others have based work on is a bad idea, because anyone downstream is forced to fix their history by hand. Its own advice is that the real fix is to avoid rebasing the upstream in the first place.
So the working rule is simple. Rebase your own, unpublished branch freely. Do not rebase a branch other people or other agents have pulled.
Useful forms
**Interactive rebase** cleans up a messy branch before you share it:
git rebase -i mainGit opens a todo list. Change pick to reword to edit a message, squash or fixup to fold a commit into the previous one, or drop to remove it.
**Moving a branch with onto** transplants commits to a new base:
git rebase --onto main next topicThis moves topic from being based on next to being based on main.
When a conflict appears
Rebase stops at the first commit that conflicts. Fix the files, stage them, then continue. The manual's options are:
git rebase --continueafter you resolve the conflictgit rebase --skipto drop the current commitgit rebase --abortto stop and reset to the original branch
With an AI agent in the loop, handling merge conflicts with AI coding agents has the review habits that apply here too.
Undoing a rebase
A finished rebase is not final. The manual notes that the previous tip of the branch is reachable through the reflog, as @{1}. To get back:
git reflog
git reset --hard HEAD@{1}Look at the reflog output first and pick the entry from just before the rebase, since other commands add entries too. The manual also warns that ORIG_HEAD is not guaranteed to still point at the old tip after a rebase, so the reflog is the safer route.
If an AI agent runs git for you
Agents sometimes rebase to tidy a branch, and the risk is the shared-branch rule above. Put these in your instructions: never rebase a branch that has been pushed, never force-push to main, and ask before any history rewrite. Back this up with server-side rules: branch protection for an AI coding agent blocks force pushes even if the instructions are ignored. More in using git with AI coding agents and the AI coding tools overview.
FAQ
What is the difference between git merge and git rebase?
Merge joins two histories with a merge commit and keeps IDs intact. Rebase replays your commits on a new base, giving a linear history with new commit IDs.
Is git rebase safe?
On your own unpublished branch, yes, and you can undo it through the reflog. On a branch others use, the Git manual advises against it.
What does git rebase --onto do?
It lets you pick the starting point for the new commits, so you can move a branch from one base to another.
How do I undo a git rebase?
Run git reflog, find the entry from before the rebase, and reset your branch to it. Abort an in-progress rebase with git rebase --abort.
How did this land?
About the author
Developer Advocate
Steve builds something with Swarmz every week and writes up what worked, what broke, and what he'd do differently. Tutorials and hands-on guides are his lane.
