Git/You have learned to merge branches, but merging creates a tangled history with merge commits that clutter git log. There is another way to integrate changes that keeps your history looking like a straight line. It is called rebaseWhat is rebase?A Git operation that replays your branch's commits on top of another branch's latest commit, creating a linear history instead of a merge commit., and understanding when to use it versus when to merge is a critical skill that AI tools consistently get wrong.
Think of rebase like editing a film. You shot some scenes (commits) on your feature branch while the main storyline moved forward. Rebase lets you re-edit your scenes so they appear to come right after the latest main storyline, as if you had started from the updated version all along.
git rebase on branches that teammates are actively working on. They treat rebase and merge as interchangeable, but rebasing a shared branch rewrites history that other people depend on. This is the most common and most dangerous rebase mistake.How rebaseWhat is rebase?A Git operation that replays your branch's commits on top of another branch's latest commit, creating a linear history instead of a merge commit. works
When you run git rebase main on your feature branch, Git performs three steps behind the scenes:
- Saves your feature branch commits to a temporary area
- Moves your branch pointer to the tip of main
- Replays your commits one by one on top of the new base
Before rebase:
main: A---B---C---D
\
feature: E---F---GAfter rebase:
main: A---B---C---D
\
feature: E'--F'--G'Notice the prime symbols (E', F', G'). These are new commits with different hashes because Git recreated them on a different base. The code changes are identical, but Git sees them as entirely different commits.
Why rebaseWhat is rebase?A Git operation that replays your branch's commits on top of another branch's latest commit, creating a linear history instead of a merge commit. matters
| Benefit | Explanation |
|---|---|
| Linear history | git log reads like a chronological story, no merge commit clutter |
| Cleaner blame | git blame shows exactly when each line was introduced |
| Better bisect | git bisect finds bugs faster with a linear timeline |
| Professional PRs | Pull requests show a clean sequence of logical commits |
Compare the two approaches side by side:
Merge history:
* abc1234 Merge branch 'feature' into main
|\
| * def5678 Add search feature
| * ghi9012 Add database index
|/
* jkl3456 Update dependencies
* mno7890 Fix login bugRebase history:
* abc1234 Add search feature
* def5678 Add database index
* ghi9012 Update dependencies
* jkl3456 Fix login bugThe rebase history reads top to bottom like a clean changelog. No merge commits, no branching arrows.
The golden rule: never rebaseWhat is rebase?A Git operation that replays your branch's commits on top of another branch's latest commit, creating a linear history instead of a merge commit. shared commits
This is the single most important thing to understand about rebase. Rebase rewrites history. Those new commitWhat is commit?A permanent snapshot of your staged changes saved in Git's history, identified by a unique hash and accompanied by a message describing what changed. hashes mean that anyone who has your old commits will see a completely different timeline when they pull.
# NEVER DO THIS:
git checkout main
git rebase feature # Rewrites main's history
git push --force # Breaks everyone's repositoryWhen to rebase vs merge:
| Use rebase when... | Use merge when... |
|---|---|
| Your branch is local and unpushed | The branch is shared with teammates |
| You want clean history before a PR | You want to preserve exact history |
| You are updating your branch with main | You are integrating a finished feature into main |
| You are cleaning up commits before review | You are closing a long-running branch |
Basic rebaseWhat is rebase?A Git operation that replays your branch's commits on top of another branch's latest commit, creating a linear history instead of a merge commit. workflow
Here is the typical flow for keeping a feature branch up to date:
# 1. Make sure you are on your feature branch
git checkout feature/add-search
# 2. Fetch the latest changes from remote
git fetch origin
# 3. Rebase your commits on top of latest main
git rebase origin/main
# 4. If there are conflicts, resolve them
# (edit files, then:)
git add .
git rebase --continue
# 5. Push your rebased branch (force needed because history changed)
git push --force-with-lease--force-with-lease flag is safer than --force because it checks if anyone else has pushed to the branch since your last fetch. If they have, it refuses to push and warns you.Pull with rebase
You can make git pull automatically rebase instead of creating merge commits:
# One time
git pull --rebase origin main
# Or configure it permanently
git config --global pull.rebase trueThis keeps your local branches linear without any extra effort.
Quick reference
| Command | What it does |
|---|---|
git rebase main | Replay current branch commits on top of main |
git rebase --abort | Cancel rebase and return to the state before |
git rebase --continue | Continue rebase after resolving a conflict |
git rebase --skip | Skip the current commit (use with caution) |
git pull --rebase | Fetch and rebase instead of creating a merge commit |
git push --force-with-lease | Force push safely after rebase |