Rebasing is one of Git's most powerful yet misunderstood features. While merging combines branches by creating a new commit that joins two histories, rebasing takes a different approach by reapplying your commits on top of another branch's history. This guide will explain what rebasing is, how to use it effectively, and when to choose it over merging.
🎥 Video: Git Merge vs Rebase (16 mins) - Understanding the differences between rebasing and merging
Rebasing is a Git operation that moves or combines a sequence of commits to a new base commit. Unlike merging, which creates a new commit to join histories, rebasing rewrites the commit history by creating new commits for each commit in the original branch.
The term "rebase" literally means to change the base of your branch from one commit to another, making it appear as if you'd created your branch from a different commit.
After rebasing onto main:
💡 Tip: Notice how commits D and E have been recreated as D' and E' with new commit hashes after the rebase.
Rebasing works by identifying the common ancestor of the two branches, collecting the changes introduced by the branch you're on, and then replaying those changes on top of the target branch.
The process can be broken down into these steps:
Imagine you have this situation:
# Starting on main branch
$ git checkout -b feature/login # Create feature branch
# Make some changes
$ git commit -m "Add login form"
$ git commit -m "Add authentication logic"
# Meanwhile, main branch progresses
$ git checkout main
# Some changes by other devs
$ git pull origin mainTo rebase your feature branch onto the updated main:
$ git checkout feature/login
$ git rebase mainRebasing and merging are both designed to integrate changes from one branch into another, but they do it in different ways and serve different purposes.
⚠️ Golden Rule of Rebasing: Never rebase a branch that others have based work on or pulled. Stick to rebasing your own local branches that aren't shared.
🎥 Video: Learn Git Rebase in 6 minutes (6 mins) - Demonstration with animations
Here's a typical workflow that incorporates rebasing:
# Start a new feature
$ git checkout -b feature/new-payment
# Make changes and commit
$ git add payment.js
$ git commit -m "Add payment form"
# Make more changes
$ git add payment-processing.js
$ git commit -m "Add payment processing"
# Keep your branch updated with main
$ git fetch origin
$ git rebase origin/main# Ensure your branch is up-to-date with main
$ git checkout main
$ git pull
$ git checkout feature/new-payment
$ git rebase main
# Push your changes (force push needed after rebase)
$ git push origin feature/new-payment --force-with-lease💡 Tip: Forcing is necessary after rebasing because the commit history has changed. Using
--force-with-leaseis safer than--forceas it prevents overwriting others' work.
The above workflow can be visualized as follows:
Conflicts during a rebase happen for the same reasons as merge conflicts: Git can't automatically determine how to combine changes. However, they're handled slightly differently.
During a rebase, Git applies each of your commits one by one on top of the target branch. If a conflict occurs, the rebase pauses at the problematic commit and lets you resolve the conflict.
$ git rebase main
Auto-merging payment.js
CONFLICT (content): Merge conflict in payment.js
error: could not apply a2b3c4d... Add payment validation
Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".# After manually resolving conflicts in your editor
$ git add payment.js
$ git rebase --continueIf you encounter multiple conflicts, you may need to repeat this process several times, once for each commit that causes conflicts.
⚠️ Note: Unlike merge, rebase makes you resolve conflicts on a commit-by-commit basis, which can mean resolving the same conflict multiple times if several of your commits modify the same part of a file.
Follow the golden rule: never rebase branches that others have based work on. Stick to rebasing your private feature branches.
Make sure your team has a shared understanding of when rebasing is appropriate and when it's not.
Before sharing your work, use interactive rebasing to clean up your commit history:
$ git rebase -i HEAD~3 # Rebase the last 3 commitsThis opens an editor with options for each commit. To make rebasing simpler, you can squash commits together into one, so that you only have to resolve conflicts once.
pick a2b3c4d Add payment form
pick b3c4d5e Fix typo in payment form
pick c4d5e6f Add payment processing
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup <commit> = like "squash", but discard this commit's log message
# ...
When fixing a previous commit, use the --fixup option:
$ git commit --fixup a2b3c4dLater, use autosquash to automatically organize and combine these during an interactive rebase:
$ git rebase -i --autosquash mainAlways test your code after a rebase to ensure nothing broke in the process.
After rebasing, you'll need to force push, but use --force-with-lease for safety:
$ git push --force-with-lease# Rebase current branch onto main
$ git rebase main
# Rebase feature branch onto main
$ git checkout feature/branch
$ git rebase main# Start an interactive rebase of the last 5 commits
$ git rebase -i HEAD~5
# Interactively rebase all commits different from main
$ git rebase -i main# Continue rebase after resolving conflicts
$ git rebase --continue
# Skip the current commit in the rebase
$ git rebase --skip
# Abort the rebase and return to the original state
$ git rebase --abort# Automatically squash fixup commits
$ git rebase -i --autosquash main
# Rebase and run tests after each commit
$ git rebase -x "npm test" main