Browse cheat sheets · Git

Technology: GitCategory: Version ControlDifficulty: IntermediateUpdated

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
  1. Problem
  2. Quick answer
  3. Code / commands
  4. 1. Check the working tree before rebasing
  5. 2. Fetch the latest remote state first
  6. 3. Rebase the current branch onto latest main
  7. 4. Rebase onto a local main branch
  8. 5. Check what will be rebased
  9. 6. Inspect the branch graph
  10. 7. Find the merge base
  11. 8. Resolve a rebase conflict
  12. 9. List unresolved files
  13. 10. Inspect conflict content
  14. 11. Continue after resolving conflicts
  15. 12. Skip a commit only when it is truly no longer needed
  16. 13. Abort the rebase
  17. 14. Quit a rebase without resetting branch state
  18. 15. Push a rebased feature branch
  19. 16. Why --force-with-lease is safer
  20. 17. Do not rebase shared integration branches casually
  21. 18. Interactive rebase recent commits
  22. 19. Common interactive rebase actions
  23. 20. Reword a commit message
  24. 21. Squash related commits
  25. 22. Use fixup for cleanup commits
  26. 23. Drop an unwanted local commit
  27. 24. Reorder commits
  28. 25. Edit a commit during interactive rebase
  29. 26. Split one commit into several commits
  30. 27. Use autosquash with fixup commits
  31. 28. Create a fixup commit from current changes
  32. 29. Rebase a branch onto a different base
  33. 30. Inspect commits before using --onto
  34. 31. Rebase one branch while checked out on another
  35. 32. Preserve merge topology with --rebase-merges
  36. 33. Avoid rebasing merge-heavy shared history casually
  37. 34. Check current rebase state
  38. 35. Edit the remaining rebase todo list
  39. 36. Recover after an accidental rebase using reflog
  40. 37. Create a backup branch before rebasing
  41. 38. Compare before and after rebase
  42. 39. Verify feature content after rebase
  43. 40. Run tests after conflict resolution
  44. 41. Rebase onto latest remote main without switching branches
  45. 42. Configure pull behavior deliberately
  46. 43. Rebase with autostash when appropriate
  47. 44. Avoid rebasing uncommitted generated or environment files
  48. 45. Rebase only commits that belong to the feature
  49. 46. Do not rebase solely to make history “look clean”
  50. 47. Understand that commit IDs change
  51. 48. Rebase can replay conflicts multiple times
  52. 49. Use rerere only if your team understands it
  53. 50. Use merge instead when rebase risk is higher than the benefit
  54. What the result means
  55. What to look for
  56. Push is rejected after successful rebase
  57. Rebase includes unexpected commits
  58. Same conflict appears repeatedly
  59. Rebase completed but feature diff changed
  60. A commit disappeared
  61. Teammate says their branch broke after your force push
  62. Production notes
  63. Rebase is safest before sharing
  64. Force-with-lease should still be intentional
  65. CI/CD references commit IDs
  66. Conflict resolution can change behavior
  67. Interactive rebase is for history design
  68. Backup branches and reflog make local rewriting safer
  69. Common mistakes
  70. 1. Rebasing without fetching first
  71. 2. Rebasing shared branches
  72. 3. Force-pushing with --force
  73. 4. Using --skip just to get past a conflict
  74. 5. Treating conflict resolution as mechanical
  75. 6. Using interactive rebase on already-shared history without coordination
  76. 7. Reordering dependent commits incorrectly
  77. 8. Squashing unrelated commits
  78. 9. Assuming rebase preserves exact content automatically
  79. 10. Using rebase when merge is simpler and safer
  80. Next step
  81. 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.


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.

Next step

Use the branch state to choose the next action.

  • Private feature branch is behind main → fetch, then rebase onto origin/main.
  • Branch is already shared heavily → prefer merge unless rewriting is coordinated.
  • Need to clean up local commits → use interactive rebase.
  • Need to combine fixup commits → use --fixup + --autosquash.
  • Branch started from wrong base → inspect the commit range, then use rebase --onto.
  • Conflict appears → resolve, stage, and rebase --continue.
  • Rebase direction/base is wrong → git rebase --abort.
  • Rebase succeeded but remote rejects push → use --force-with-lease only if remote rewriting is expected.
  • Think work disappeared → inspect git reflog.
  • Conflicts are too complex for safe replay → abort and consider merge.

← All cheat sheets