Skip to content

git rebase

Replaying commits with git rebase — keeping history linear and resolving rebase conflicts.

What you'll learn

  • How rebase replays your commits on top of another branch
  • Why rebase creates a cleaner, linear history than merge
  • Interactive rebase for squashing, reordering, and editing commits
  • The golden rule: never rebase commits you have pushed

Concept

What git rebase Does

git rebase takes your commits and replays them on top of another branch. This rewrites history to make it look like your branch was created from the latest commit of the target branch, resulting in a clean, linear history.

git checkout feature-login
git rebase main

This replays your feature branch commits on top of the latest main.

Merge vs Rebase

With merge:           With rebase:
A---B---C---M  (main)     A---B---C---D'---E'  (main)
         \                          ^
          D---E  (feature)          |
                              (feature rebased)
  • Merge preserves both histories with a merge commit (M). The history shows the branch divergence.
  • Rebase replays your commits (D→D', E→E') on top of main. The history is linear — no merge commit.

Rebase produces cleaner history but rewrites commit hashes. The commits are not the same — they are new commits with the same changes.

When to Rebase

Rebase is ideal for:

  • Updating a feature branch with the latest main before merging
  • Cleaning up your commit history before a PR (squash, reorder, reword)
  • Keeping a linear history in your project's main branch
# Before merging a feature, rebase it on the latest main
git fetch origin
git checkout feature-login
git rebase origin/main
# resolve any conflicts, then:
git push --force-with-lease origin feature-login
# Now merge into main (will be a fast-forward, no merge commit)

Interactive Rebase

git rebase -i lets you rewrite history commit by commit:

git rebase -i HEAD~3

This opens an editor listing the last 3 commits:

pick abc1234 Add login form
pick def5678 Add validation
pick ghi9012 Fix typo in error message

You can change pick to:

  • pick — keep the commit as is
  • reword — keep the commit but change its message
  • squash — combine this commit with the previous one
  • fixup — like squash but discard this commit's message
  • drop — remove the commit entirely
  • edit — pause to modify the commit's content

Squashing Commits

pick abc1234 Add login form
squash def5678 Add validation
squash ghi9012 Fix typo in error message

This combines all three into a single commit. You then edit the combined commit message.

Resolving Rebase Conflicts

If a commit cannot be replayed cleanly, rebase pauses:

git rebase origin/main
# CONFLICT (content): Merge conflict in login.js

# Resolve the conflict, then:
git add login.js
git rebase --continue

# To skip this commit:
git rebase --skip

# To cancel the rebase entirely:
git rebase --abort

Rebase conflicts are resolved one commit at a time, which can be more work than a single merge conflict. --abort is your escape hatch.

The Golden Rule of Rebase

Never rebase commits that you have already pushed to a shared branch.

Rebase rewrites commit hashes. If someone else has pulled your original commits, their history will diverge from your rebased history, creating a mess.

  • ✅ Rebase your local feature branch before pushing
  • ✅ Rebase a branch that only you use
  • ❌ Rebase main or any shared branch
  • ❌ Rebase commits that others may have pulled

If you rebase a pushed branch, you must force push (git push --force-with-lease), which can overwrite others' work.

Rebase vs Merge: Guidelines

  • Feature branches: rebase onto main before merging (clean history)
  • Main branch: never rebase (others depend on it)
  • Long-lived branches: merge (rebase would be too disruptive)
  • Small teams: rebase for linear history
  • Large teams: merge to preserve the branch history and avoid force-push issues

Example

              # --- Basic rebase: update feature branch with latest main ---
git fetch origin
git checkout feature-login
git rebase origin/main
# if conflicts occur, resolve them:
git add conflicted-file.js
git rebase --continue
# push the rebased branch (force needed because history changed)
git push --force-with-lease origin feature-login

# --- Interactive rebase: squash last 3 commits ---
git rebase -i HEAD~3
# In the editor, change to:
# pick abc1234 Add login form
# squash def5678 Add validation
# squash ghi9012 Fix typo
# Save and edit the combined commit message

# --- Interactive rebase: reword a commit ---
git rebase -i HEAD~3
# change 'pick' to 'reword' for the commit you want to rename
# save, then edit the commit message

# --- Interactive rebase: drop a commit ---
git rebase -i HEAD~5
# change 'pick' to 'drop' for commits to remove
# or just delete the line

# --- Rebase to reorder commits ---
git rebase -i HEAD~3
# Just reorder the lines in the editor

# --- Abort a rebase that is going wrong ---
git rebase --abort

# --- Skip a commit that cannot be applied ---
git rebase --skip

# --- Pull with rebase (combine fetch + rebase) ---
git pull --rebase origin main

# --- Configure pull to always rebase ---
git config --global pull.rebase true
            

Shows basic rebase, interactive rebase for squashing/rewording/dropping/reordering commits, conflict resolution, aborting, skipping, and pull --rebase. The --force-with-lease flag is essential after rebasing a pushed branch. The golden rule: never rebase shared commits.

Try it

  • Code Diff

    Review changes before rebasing to anticipate conflicts.

  • CI/CD YAML Generator

    Rebased branches trigger CI — generate a pipeline to verify.

Common mistakes

The mistake

Rebasing commits that were already pushed and others have pulled

The fix

The golden rule: never rebase shared commits. Rebase rewrites commit hashes, so anyone who pulled the original commits will have divergent history. Only rebase local, unpushed commits or your own feature branch that no one else uses. If you must rebase a pushed branch, coordinate with your team and use --force-with-lease.

The mistake

Using git push --force instead of --force-with-lease after a rebase

The fix

git push --force blindly overwrites the remote, potentially destroying teammates' commits. git push --force-with-lease only force pushes if the remote has not changed since you last fetched. Always use --force-with-lease after rebasing — it is the safe alternative to --force.

Related Cheatsheets

Practice git rebase

5 exercises

Practice git rebase

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors