Git Rebase: Write History Your Team Can Actually Read
Your commit history is documentation that blame, bisect and change-coupling analysis depend on. Here's how to use git rebase to keep it readable, safely.
Six months from now, someone will run git blame on a line you wrote this week and land on a commit called "wip". That's the real audience for git rebase: not the reviewer looking at your pull request today, but the engineer bisecting a regression next year with nothing but your commit messages to go on.
Most teams treat rebase as a merge-conflict chore or a source of fear. I think that framing is backwards. Rebase is an editing tool for your project's most underused documentation, and it deserves a team policy, not a shrug.
Look at what reads your history. git log answers "what changed and why". git blame answers "who touched this line, in which change". git bisect binary-searches commits to find the one that broke something, and it only works if each commit builds and does one thing. Change-coupling and hotspot analysis mine the same log to find files that always change together. I've written about using git history as a codebase analysis tool and about behavioral code analysis; both get sharper when commits are coherent and blurrier when every third commit is "fix typo" or "address review comments".
The Pro Git book frames the debate well. One camp treats commit history as a record of what actually happened, mess included. The other treats it as the story of how the project was made, edited for future readers before it's published. My view: your private branch is a draft, and main is the published book. Rebase is how a draft becomes a chapter.[1]
# Git Rebase vs Merge: What Each Does to the Graph
Both commands integrate work from one branch into another. They leave very different shapes behind. Here's the same repository, run both ways: main has commits A, B and C, and feature branched at B with D and E.
bash
# Option 1: merge main and featuregit switch maingit merge featuregit log --graph --format=%s# * Merge branch 'feature'# |\# | * E add tests# | * D add parser# * | C# |/# * B# * A# Option 2, instead of option 1, from the same starting point:# replay feature on top of maingit switch featuregit rebase maingit log --graph --format=%s# * E add tests# * D add parser# * C# * B# * A
Merge keeps both lines of work and adds a merge commit with two parents. Rebase takes D and E, replays them on top of C, and creates new commits with new hashes. The originals don't vanish immediately: they're still reachable through the reflog until it expires, which matters later when we talk about recovery.
Figure 1. Merge records when an integration happened; rebase rewrites the branch into a single line of new commits.
By default, a rebase drops merge commits from the branch it replays and produces a single linear line. If your branch contains merges you care about, git rebase --rebase-merges tries to recreate them, though any conflict resolutions inside those merges have to be redone by hand.[2]
Here's my contrarian take. "Always rebase, never merge" is a fine rule for short-lived feature branches and a bad rule for long-lived integration branches. A release branch, a shared develop or a long-running migration branch has many people building on it. Rebasing it rewrites commits others already have. And the merge commit itself carries information: it records when an integration happened, which is exactly what you want when you're asking "did the hotfix reach the release branch before or after the incident?"
# Interactive Rebase: Edit the Story Before It Ships
Interactive rebase opens a todo list of the commits you're about to replay and lets you change what happens to each one. Run git rebase -i origin/main and Git shows something like this, oldest first:
Change the verb on each line to tell Git what to do:
Command
What it does
Use it when
pick
Keep the commit as is
The commit already says one clear thing
reword
Keep the change, edit the message
The message is "wip" or "fix"
edit
Stop after applying, so you can amend or split
One commit mixes two unrelated changes
squash
Fold into the previous commit, combine messages
Two commits are one idea and both messages matter
fixup
Fold into the previous commit, drop this message
A follow-up fix to an earlier commit on the branch
drop
Remove the commit
Debug logging, experiments, accidental files
Two variants worth knowing: fixup -C uses the fixup commit's message instead of the original's, and fixup -c does the same but opens the editor first. There's also exec, which runs a shell command after a line, so exec npm test between picks checks that each commit still passes on its own. That is the property git bisect depends on.
The better habit is to mark fixes at the moment you make them. Say a reviewer finds a bug in the "Add orders table" commit, three commits back:
bash
git add schema.sqlgit commit --fixup=":/^Add orders table" # or --fixup=<commit-hash>git rebase -i --autosquash origin/main
git commit --fixup creates a commit titled fixup! Add orders table. When you rebase with --autosquash, Git moves that commit directly under its target and marks it fixup, so the todo list arrives already sorted. Save it and the fix folds into the commit where it belongs. Two more forms exist: --fixup=amend:<commit> also replaces the target's message, and --fixup=reword:<commit> changes only the message.[3]
Figure 2. Fixup commits name their target, so autosquash can fold them in without hand-editing the todo list.
Set rebase.autoSquash to true and every interactive rebase sorts fixups for you, no flag needed. The config applies to interactive mode; you can still pass --autosquash explicitly on a plain rebase.
If you split a large change into a stack (orders-schema, then orders-api on top of it, then orders-ui on top of that), rebasing the top branch leaves the lower branches pointing at stale commits unless you pass --update-refs: it force-updates every local branch that points at a commit being rebased.
bash
git switch orders-uigit rebase --update-refs main# Updated the following refs with --update-refs:# refs/heads/orders-api# refs/heads/orders-schemagit push --force-with-lease origin orders-schema orders-api orders-ui
Set rebase.updateRefs to true to make it the default. Branches checked out in another worktree are not updated this way.
Rebasing a long branch repeatedly means resolving the same conflict again and again. rerere ("reuse recorded resolution") records how you resolved a conflict and replays that resolution the next time the same conflict appears. Turn it on with git config rerere.enabled true. On the second rebase, Git prints a line like "Resolved 'schema.sql' using previous resolution." The file is fixed but not staged, so you still review it, git add it and run git rebase --continue.[4]
Rebase feels dangerous because it rewrites commits. It is far harder to lose work than people think, because every change to a branch tip is written to the reflog.
bash
# Mid-rebase and it's going badlygit rebase --abort# Rebase finished, but the result is wronggit reflog show feature # every position the branch has heldgit reset --hard feature@{1} # the tip before the last change
feature@{1} means "where this branch pointed one change ago". ORIG_HEAD usually points at the pre-rebase tip too, but the git-rebase docs warn it's not guaranteed if you ran other commands like git reset during the rebase, so I reach for the branch reflog first. Commits that no branch points to any longer stay in the reflog for 30 days by default (gc.reflogExpireUnreachable), so you have time.[5]
# Force Pushing Without Destroying a Teammate's Work
After a rebase, your local branch and the remote have diverged, so a plain git push is rejected. The reflexive fix, git push --force, overwrites whatever is on the remote, including commits a teammate pushed five minutes ago.
--force-with-lease is the safer default. It only overwrites the remote branch if it still points where your remote-tracking branch says it does. Try it in a scratch repository: when a teammate has pushed to the same branch since your last fetch, the leased push is refused with ! [rejected] feature -> feature (stale info).
There's a catch the docs spell out. The lease compares against your remote-tracking ref, so anything that fetches in the background (an IDE, a cron job) quietly updates that ref and the lease passes. Run git fetch and repeat the same --force-with-lease push: it goes through and the teammate's commit disappears from the remote branch. Adding --force-if-includes closes the gap by checking that the remote tip appears in your local branch's reflog, meaning you actually integrated it. With both flags, that push is rejected with "remote ref updated since checkout". Set push.useForceIfIncludes to true and you get it every time.[6]
Pro Git's rule fits in one line: don't rebase commits that exist outside your repository if other people may have built work on them. Your own pushed feature branch, which only you commit to, is fine to rewrite with a lease. main, release branches and any branch two people commit to are not. If you break this rule, everyone downstream has to repair their history by hand, which the git-rebase manual describes as a bad idea for exactly that reason.
The platform matters here too. GitHub's "Rebase and merge" button doesn't fast-forward your exact commits: it always creates new commit SHAs and updates the committer information. "Squash and merge" collapses the whole pull request into one commit. Both are valid. Both should be chosen on purpose.[7]
This is the table I'd put in a team's contributing guide. Copy it and change the cells you disagree with.
Situation
Policy
Why
Your own feature branch, before review
Rebase freely, interactive rebase encouraged
Nobody else has these commits yet
Your own branch, during review
Add --fixup commits, autosquash before merge
Reviewers see what changed since their last look
Updating a branch with new main
git fetch then git rebase origin/main
Keeps the branch linear and reviewable
Branch two or more people commit to
Merge main in, no rewriting
Rewriting breaks their local copies
Long-lived release or integration branch
Merge only, force pushes blocked
Merge commits record when integration happened
main
Force pushes blocked in branch protection
The published history never changes
PR merge button, curated commits
Rebase-merge or merge commit
Keeps each commit for blame and bisect
PR merge button, messy commits
Squash-merge as the fallback
One clean commit beats ten noisy ones
Any force push
--force-with-lease --force-if-includes
Never overwrite work you haven't seen
My second contrarian take: squash-merging every pull request by default is a trade of a messy history for a lossy one. A pull request that adds a migration, an endpoint and a UI becomes one commit. git bisect can no longer tell you which of the three broke checkout, and git blame points at a single giant change. I'd rather teach people to curate commits and keep them. Squash is the fallback for PRs where nobody did.
If you track pull request data, commit structure shows up there as well: code review analytics gets more honest when one commit means one reviewable idea.
This is the routine I'd suggest. The config is a one-time setup.
bash
# One-time setupgit config --global rebase.autoSquash truegit config --global rebase.updateRefs truegit config --global rerere.enabled truegit config --global push.useForceIfIncludes true# Start of the day: catch up with maingit fetch origingit rebase origin/main# While working: commit small, and point fixes at their targetgit commit -m "Add orders endpoint"git commit --fixup=":/^Add orders table"# Before asking for review: tidy, then push safelygit rebase -i origin/maingit push --force-with-lease
Commit history is documentation that git log, git blame, git bisect and change-coupling analysis all read. Edit it before it lands.
Rebase your own short-lived branches freely. Merge long-lived shared branches, and never rewrite commits others have built on.
Use git commit --fixup with rebase.autoSquash so fixes fold into the right commit without hand-editing todo lists.
Push rewritten branches with --force-with-lease plus --force-if-includes. A lease alone can be defeated by a background fetch.
Squash-merge is a fallback for messy PRs, not a default for curated ones.
Your history will outlive most of the code in it. Write it for the person who has to read it.
Frequently asked questions
Is git rebase better than git merge?
Neither is better in general. Rebase gives a linear history and suits short-lived branches only you commit to. Merge keeps both lines of work and records when an integration happened, which suits long-lived shared branches such as release branches. Most teams need both, with a written rule for which branch gets which.
Should we squash-merge every pull request?
I'd make it a fallback, not the default. Squashing turns a pull request with several distinct changes into one commit, so git bisect and git blame lose the ability to point at the specific change. If the author curated their commits, keep them with rebase-merge or a merge commit; squash the pull requests where nobody did.
How do I undo a git rebase?
While the rebase is still running, git rebase --abort puts everything back. After it finishes, git reflog show on your branch lists every position it has held, and git reset --hard to the branch name followed by @{1} returns it to the tip before the rebase. ORIG_HEAD usually works too, but the docs say it is not guaranteed.
When should I not use git rebase?
Don't rebase commits that exist outside your repository if other people may have built work on them. That rules out main, release branches and any branch two or more people commit to. Rewriting those forces everyone downstream to repair their history by hand. Merge into them instead and block force pushes on them.
Five predictions for where code intelligence is heading by 2028, based on 6 years of building tools in this space. Includes what's real, what's overhyped, and a maturity model for planning.
Most code quality dashboards fail because they track too many metrics and live outside the team's workflow. Here are exactly 7 metrics and a 3-week adoption plan that actually works.
Build software composition analysis into CI with dependency inventories, vulnerability checks and licence review. Define owners, response targets and follow-up.
Architecture fitness functions are automated tests for your system's structural properties. Here's how to implement the 5 most impactful ones and integrate them into your CI pipeline.
Your PR data reveals team bottlenecks invisible in standups. Here's how to measure TTFR, review distribution, and cycle time with the REVIEW framework.