Browse cheat sheets · Git
Rebase Quick Reference
Rebase Git branches safely to replay local commits onto a new base, resolve conflicts deliberately, clean up private history, and recover when a rebase goes wrong.
On this page
- Problem
- Quick answer
- Code / commands
- 1. Check the working tree before rebasing
- 2. Fetch the latest remote state first
- 3. Rebase the current branch onto latest main
- 4. Rebase onto a local main branch
- 5. Check what will be rebased
- 6. Inspect the branch graph
- 7. Find the merge base
- 8. Resolve a rebase conflict
- 9. List unresolved files
- 10. Inspect conflict content
- 11. Continue after resolving conflicts
- 12. Skip a commit only when it is truly no longer needed
- 13. Abort the rebase
- 14. Quit a rebase without resetting branch state
- 15. Push a rebased feature branch
- 16. Why --force-with-lease is safer
- 17. Do not rebase shared integration branches casually
- 18. Interactive rebase recent commits
- 19. Common interactive rebase actions
- 20. Reword a commit message
- 21. Squash related commits
- 22. Use fixup for cleanup commits
- 23. Drop an unwanted local commit
- 24. Reorder commits
- 25. Edit a commit during interactive rebase
- 26. Split one commit into several commits
- 27. Use autosquash with fixup commits
- 28. Create a fixup commit from current changes
- 29. Rebase a branch onto a different base
- 30. Inspect commits before using --onto
- 31. Rebase one branch while checked out on another
- 32. Preserve merge topology with --rebase-merges
- 33. Avoid rebasing merge-heavy shared history casually
- 34. Check current rebase state
- 35. Edit the remaining rebase todo list
- 36. Recover after an accidental rebase using reflog
- 37. Create a backup branch before rebasing
- 38. Compare before and after rebase
- 39. Verify feature content after rebase
- 40. Run tests after conflict resolution
- 41. Rebase onto latest remote main without switching branches
- 42. Configure pull behavior deliberately
- 43. Rebase with autostash when appropriate
- 44. Avoid rebasing uncommitted generated or environment files
- 45. Rebase only commits that belong to the feature
- 46. Do not rebase solely to make history “look clean”
- 47. Understand that commit IDs change
- 48. Rebase can replay conflicts multiple times
- 49. Use rerere only if your team understands it
- 50. Use merge instead when rebase risk is higher than the benefit
- What the result means
- What to look for
- Push is rejected after successful rebase
- Rebase includes unexpected commits
- Same conflict appears repeatedly
- Rebase completed but feature diff changed
- A commit disappeared
- Teammate says their branch broke after your force push
- Production notes
- Rebase is safest before sharing
- Force-with-lease should still be intentional
- CI/CD references commit IDs
- Conflict resolution can change behavior
- Interactive rebase is for history design
- Backup branches and reflog make local rewriting safer
- Common mistakes
- 1. Rebasing without fetching first
- 2. Rebasing shared branches
- 3. Force-pushing with --force
- 4. Using --skip just to get past a conflict
- 5. Treating conflict resolution as mechanical
- 6. Using interactive rebase on already-shared history without coordination
- 7. Reordering dependent commits incorrectly
- 8. Squashing unrelated commits
- 9. Assuming rebase preserves exact content automatically
- 10. Using rebase when merge is simpler and safer
- Next step
- Related deep dives
Problem
You need to update or clean up a feature branch without introducing unnecessary merge commits.
Typical rebase use cases include:
- replay a feature branch on top of the latest
main - keep a private branch history linear
- reorder, squash, or edit local commits
- remove accidental commits before opening a pull request
- resolve conflicts while replaying commits
- recover from a failed or incorrect rebase
The main risk is that rebase rewrites commit history.
That is safe for private or intentionally rewritten feature branches, but dangerous for shared commits that teammates already depend on.
Quick answer
Update a private feature branch onto latest main:
git status
git fetch origin
git rebase origin/main
If conflicts occur:
git status
# edit conflicted files
git add path/to/resolved-file
git rebase --continue
Abort if necessary:
git rebase --abort
If the branch was already pushed and rewriting it is acceptable:
git push --force-with-lease
The central rule is:
Private feature history
→ rebase is usually safe
Shared history
→ avoid rewriting unless the team explicitly coordinates it
Code / commands
1. Check the working tree before rebasing
git status
Prefer a clean working tree before starting.
If unrelated changes exist:
git stash push -u -m "WIP before rebase"
or commit them on the appropriate branch.
Do not start a complex rebase with unrelated uncommitted work unless you understand exactly how Git will handle it.
2. Fetch the latest remote state first
git fetch origin
This updates:
origin/main
origin/develop
origin/feature/...
without changing your current working tree.
Do not rebase onto a stale local view of the remote branch.
3. Rebase the current branch onto latest main
git rebase origin/main
Conceptually:
Before:
A---B---C origin/main
\
D---E feature
After:
A---B---C origin/main
\
D'---E' feature
D' and E' are new commits with new commit IDs.
4. Rebase onto a local main branch
If local main is already current:
git rebase main
Safer workflow:
git switch main
git pull --ff-only
git switch feature/report-engine
git rebase main
Using origin/main after git fetch is often more direct.
5. Check what will be rebased
Before rebasing:
git log --oneline origin/main..HEAD
This shows commits unique to your current branch.
Those are the commits Git will typically replay.
6. Inspect the branch graph
git log \
--oneline \
--graph \
--decorate \
--all \
-30
Use this when branch ancestry is not obvious.
Do not rebase until you understand which branch is the base and which commits are unique to your branch.
7. Find the merge base
git merge-base origin/main HEAD
This identifies the common ancestor.
It is useful when a branch was created from an unexpected base.
8. Resolve a rebase conflict
When Git stops:
git status
Open conflicted files and resolve the intended final content.
Then stage:
git add path/to/file
Continue:
git rebase --continue
Repeat until all commits have been replayed.
9. List unresolved files
git diff --name-only --diff-filter=U
Use during a large conflict resolution.
10. Inspect conflict content
git diff
Conflict markers can look like:
<<<<<<< HEAD
base branch version
=======
rebased commit version
>>>>>>> commit-message
During a rebase, the meaning of ours and theirs can be unintuitive because Git is replaying commits onto the new base.
Do not choose sides mechanically.
Resolve the code based on the intended final state.
11. Continue after resolving conflicts
git add src/app.py
git rebase --continue
If Git opens the commit message editor, review the message before continuing.
12. Skip a commit only when it is truly no longer needed
git rebase --skip
Use this only if the current commit’s changes are already present or intentionally discarded.
Skipping a commit removes that commit from the rebased branch.
Do not use --skip simply to get past a conflict.
13. Abort the rebase
git rebase --abort
This returns the branch to its pre-rebase state.
Use when:
- you started from the wrong base
- conflicts reveal the approach is unsafe
- you need to rethink the branch history
Abort is preferable to improvising destructive resets during an active rebase.
14. Quit a rebase without resetting branch state
git rebase --quit
This stops the rebase machinery without necessarily restoring the original branch state.
Use only when you understand the difference from:
git rebase --abort
For most recovery scenarios, --abort is the safer choice.
15. Push a rebased feature branch
If the branch was never pushed:
git push -u origin feature/report-engine
If it was already pushed and rewriting it is acceptable:
git push --force-with-lease
Prefer this over:
git push --force
16. Why --force-with-lease is safer
--force-with-lease checks that the remote branch still points to the commit your local repository expects.
If someone else pushed new commits, the force push is refused.
This reduces the chance of overwriting another developer’s work.
It does not make history rewriting risk-free.
17. Do not rebase shared integration branches casually
Avoid rewriting:
main
develop
release
shared team branches
unless the repository workflow explicitly requires and coordinates it.
Rebase is most appropriate for private or intentionally rewritable feature branches.
18. Interactive rebase recent commits
git rebase -i HEAD~5
This opens the last five commits in an interactive todo list.
Example:
pick a1b2c3d Add report endpoint
pick d4e5f6a Fix typo
pick 1112223 Add validation
pick 3334445 Debug logging
pick 5556667 Remove debug logging
You can change the action for each commit.
19. Common interactive rebase actions
Typical commands:
pick
reword
edit
squash
fixup
drop
Use:
pick
→ keep commit
reword
→ keep changes, edit message
edit
→ pause so you can modify commit
squash
→ combine with previous commit and edit combined message
fixup
→ combine with previous commit and discard this commit message
drop
→ remove commit
20. Reword a commit message
Interactive rebase:
git rebase -i HEAD~3
Change:
pick a1b2c3d bad message
to:
reword a1b2c3d bad message
Git will stop so you can edit the message.
21. Squash related commits
Example todo list:
pick a1b2c3d Add report endpoint
squash d4e5f6a Add validation
squash 1112223 Fix endpoint naming
Git combines the commits into one.
Use this when the final history is clearer as one logical change.
Do not squash unrelated work just to reduce commit count.
22. Use fixup for cleanup commits
Example:
pick a1b2c3d Add report endpoint
fixup d4e5f6a Fix typo
fixup 1112223 Remove debug print
The final commit keeps the first commit’s message.
This is useful for small corrective commits made during development.
23. Drop an unwanted local commit
Interactive rebase:
pick a1b2c3d Add endpoint
drop d4e5f6a Add temporary debug file
pick 1112223 Add tests
Or delete the line in the todo list.
Use only for unpublished commits or when coordinated history rewriting is acceptable.
24. Reorder commits
Interactive rebase allows changing commit order:
pick 1112223 Add data model
pick a1b2c3d Add endpoint
pick d4e5f6a Add tests
instead of:
pick a1b2c3d Add endpoint
pick 1112223 Add data model
pick d4e5f6a Add tests
Only reorder if later commits still apply cleanly and the resulting history remains logically correct.
25. Edit a commit during interactive rebase
Change:
pick a1b2c3d Add endpoint
to:
edit a1b2c3d Add endpoint
When Git stops:
# modify files
git add path/to/file
git commit --amend
git rebase --continue
Use this to correct content inside an older local commit.
26. Split one commit into several commits
Start:
git rebase -i HEAD~5
Mark the target commit:
edit
When Git stops:
git reset HEAD^
This keeps the changes in the working tree but removes the commit.
Then stage and commit in logical pieces:
git add -p
git commit -m "Add report model"
git add -p
git commit -m "Add report API"
Then:
git rebase --continue
Use only on local/unshared history.
27. Use autosquash with fixup commits
Create a fixup commit:
git commit --fixup=<commit>
Then:
git rebase -i --autosquash origin/main
Git automatically places the fixup commit next to its target and marks it for fixup.
This is useful during active feature development.
28. Create a fixup commit from current changes
git add path/to/file
git commit --fixup=a1b2c3d
Later:
git rebase -i --autosquash origin/main
This keeps development fast while still producing clean history before review.
29. Rebase a branch onto a different base
Advanced syntax:
git rebase --onto <new-base> <old-base> <branch>
Example:
git rebase \
--onto origin/main \
origin/develop \
feature/report-engine
This tells Git:
Take commits on feature/report-engine
that are after origin/develop
and replay them onto origin/main
Use when a branch was created from the wrong base or needs to move between release lines.
30. Inspect commits before using --onto
Before running:
git rebase --onto ...
inspect:
git log --oneline <old-base>..<branch>
Those are the commits likely to be replayed.
If the range is wrong, do not proceed.
31. Rebase one branch while checked out on another
Modern Git supports:
git rebase origin/main feature/report-engine
This checks out the named branch internally and rebases it.
For clarity in manual workflows, switching to the branch first is often easier to reason about.
32. Preserve merge topology with --rebase-merges
git rebase --rebase-merges origin/main
Use when the feature branch contains meaningful merge commits that should be reconstructed rather than flattened.
This is an advanced workflow.
Do not use it unless preserving branch topology matters.
33. Avoid rebasing merge-heavy shared history casually
Merge commits can encode integration decisions.
Flattening or recreating them changes the historical structure.
Understand the branch model before rewriting them.
34. Check current rebase state
git status
Git will report:
- rebase in progress
- current commit being replayed
- conflicts
- commands completed/remaining
Use git status before guessing what to do next.
35. Edit the remaining rebase todo list
During an interactive rebase:
git rebase --edit-todo
Use this to modify upcoming actions.
Do not edit internal .git rebase files manually unless you understand Git internals.
36. Recover after an accidental rebase using reflog
git reflog
Find the pre-rebase branch tip.
Inspect:
git show <old-commit>
Create a recovery branch:
git switch -c recovery-before-rebase <old-commit>
Reflog is one of the safest ways to recover local history after rewriting.
37. Create a backup branch before rebasing
Before a complicated rewrite:
git branch backup-before-rebase
Then perform the rebase.
If something goes wrong:
git switch backup-before-rebase
This is cheap insurance.
38. Compare before and after rebase
Before rebasing, save the old tip:
git branch backup-before-rebase
Afterward compare:
git diff backup-before-rebase...HEAD
For a pure history cleanup, the final file content should normally remain equivalent.
39. Verify feature content after rebase
git diff origin/main...HEAD
This should still represent the intended feature change.
Also inspect:
git log --oneline origin/main..HEAD
Make sure no feature commits disappeared unexpectedly.
40. Run tests after conflict resolution
Rebase can produce code that is syntactically mergeable but logically wrong.
After conflict resolution:
build
test
lint
typecheck
as appropriate for the project.
Do not treat a conflict-free rebase as proof of correctness.
41. Rebase onto latest remote main without switching branches
Typical concise flow:
git fetch origin
git rebase origin/main
This is often the cleanest daily feature-branch update.
42. Configure pull behavior deliberately
Git can be configured to use merge, rebase, or fast-forward-only behavior for git pull.
Examples:
git config pull.rebase true
or:
git config pull.ff only
Do not change global behavior unless you understand the team’s workflow.
Explicit commands are often clearer in production engineering environments.
43. Rebase with autostash when appropriate
git rebase --autostash origin/main
Git temporarily stashes local changes and reapplies them after the rebase.
This is convenient, but it can still create conflicts when restoring the stashed work.
A clean working tree remains easier to reason about.
44. Avoid rebasing uncommitted generated or environment files
If local generated/config files differ by environment, resolve them before rebase.
Do not let untracked/generated files complicate history operations unnecessarily.
45. Rebase only commits that belong to the feature
If:
git log origin/main..HEAD
shows unrelated commits, investigate the branch base before rebasing.
You may need:
git rebase --onto
instead of a normal rebase.
46. Do not rebase solely to make history “look clean”
History cleanup should improve:
- reviewability
- revertability
- logical grouping
- understanding
Do not rewrite stable shared history for cosmetic reasons.
47. Understand that commit IDs change
After rebase:
old commit:
a1b2c3d
rebased commit:
e4f5a6b
The content may be similar, but the commit object is different because its parent/history changed.
This is why remote branches often require --force-with-lease after a rebase.
48. Rebase can replay conflicts multiple times
If several commits touch the same area, similar conflicts may appear repeatedly while each commit is replayed.
Possible responses:
- resolve each commit faithfully
- squash related commits first when appropriate
- abort and use merge if rewriting is not worth the complexity
49. Use rerere only if your team understands it
Git can remember conflict resolutions with:
git config rerere.enabled true
This can help when the same conflict recurs.
It is useful in advanced workflows, but automatic reuse of a prior resolution should still be reviewed.
50. Use merge instead when rebase risk is higher than the benefit
Prefer merge when:
- the branch is shared
- commit IDs are already referenced externally
- preserving topology matters
- conflict replay would be unnecessarily complex
- team policy forbids rewriting
Rebase is a tool, not a requirement.
What the result means
| Command | What it does | History rewritten? |
|---|---|---|
git rebase origin/main |
Replays current branch commits onto latest main | Yes |
git rebase -i |
Interactively rewrites local commit sequence | Yes |
git rebase --continue |
Continues after conflict/edit | Continues rewrite |
git rebase --skip |
Drops current replayed commit | Yes |
git rebase --abort |
Restores pre-rebase branch state | No final rewrite retained |
git rebase --onto |
Moves selected commit range to new base | Yes |
git rebase --autostash |
Temporarily stashes local work around rebase | Yes |
git push --force-with-lease |
Updates rewritten remote feature history safely-ish | Remote history rewritten |
The main distinction is:
merge
→ combines existing histories
rebase
→ rebuilds commits on a new base
What to look for
Push is rejected after successful rebase
Expected if the old version of the branch already exists remotely.
If rewriting the branch is allowed:
git push --force-with-lease
Do not use plain --force by default.
Rebase includes unexpected commits
Stop and inspect:
git log origin/main..HEAD
git merge-base origin/main HEAD
The branch may have the wrong base.
Same conflict appears repeatedly
Several replayed commits modify the same region.
Consider whether:
- commits should be squashed
- merge is simpler
- branch divergence has become too large
Rebase completed but feature diff changed
Compare:
git diff backup-before-rebase...HEAD
Unexpected content changes mean the conflict resolution likely altered behavior.
A commit disappeared
Check whether it was:
- skipped
- dropped
- absorbed as an already-applied patch
- accidentally omitted during interactive rebase
Use git reflog to recover the previous branch tip.
Teammate says their branch broke after your force push
You probably rewrote shared commits.
Stop further rewriting and coordinate recovery using reflog/known remote commit IDs.
Production notes
Rebase is safest before sharing
The best time to clean up feature history is before other developers depend on those commit IDs.
Force-with-lease should still be intentional
It is a safety check, not permission to rewrite arbitrary shared branches.
CI/CD references commit IDs
A rebase changes commit SHAs.
That can affect:
- build references
- deployment links
- code-review comments
- incident records
Do not rewrite history casually after deployment or release workflows reference it.
Conflict resolution can change behavior
Git only knows textual history.
It does not know whether the merged result preserves application semantics.
Run tests after conflict-heavy rebases.
Interactive rebase is for history design
Use it to make commits:
- focused
- logically ordered
- reviewable
- reversible
Do not reduce every feature to one giant commit automatically.
Backup branches and reflog make local rewriting safer
Before complex rewrites:
git branch backup-before-rebase
and know that:
git reflog
can often recover the old tip.
Common mistakes
1. Rebasing without fetching first
You may rebase onto stale remote state.
2. Rebasing shared branches
This changes commit IDs that other developers may depend on.
3. Force-pushing with --force
Use --force-with-lease when rewriting is actually required.
4. Using --skip just to get past a conflict
This removes the commit being replayed.
5. Treating conflict resolution as mechanical
The correct result may combine both versions.
6. Using interactive rebase on already-shared history without coordination
Every edited/squashed/reordered commit gets a new identity.
7. Reordering dependent commits incorrectly
Later commits may rely on earlier changes.
Keep logical dependencies intact.
8. Squashing unrelated commits
This harms reviewability and future reverts.
9. Assuming rebase preserves exact content automatically
Conflict resolution can alter final behavior.
Compare and test afterward.
10. Using rebase when merge is simpler and safer
A linear graph is not worth unnecessary operational risk.
Was this helpful?
What could be better?
Thanks — that helps me improve Javi Builds.
Stay in the loop
Get the Javi Builds updates you actually care about.
Check your inbox
I sent you a confirmation link. Your subscription will be active after you confirm it.