Skip to content

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.

12 min read
Modular charcoal track segments being carefully realigned onto a teal main track.
On this page

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.

Your Commit History Is Documentation

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 feature
git switch main
git merge feature
git 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 main
git switch feature
git rebase main
git 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.

git merge feature keeps both lines, adds a merge commit ABC DE M main feature records when an integration happened git rebase main replays D and E on top of C ABC DE D'E' main feature old D and E stay in the reflog linear: one parent per commit
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]

Why "always rebase" is wrong

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:

pick 4f9753a # Add orders table
pick 4e9f137 # Add orders endpoint
pick 25123f1 # Test orders endpoint
pick a56f366 # wip
pick 83ee4ab # debug logging

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.

Fixup commits and autosquash

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.sql
git 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]

Before: the branch, oldest first Add orders table Add orders endpoint Test orders endpoint fixup! Add orders table fixup! Add orders endpoint After: git rebase -i --autosquash Add orders table Add orders endpoint Test orders endpoint three commits, one idea each each fixup folded into its target
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.

Stacked branches with --update-refs

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-ui
git rebase --update-refs main
# Updated the following refs with --update-refs:
#   refs/heads/orders-api
#   refs/heads/orders-schema
git 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.

rerere for conflicts you've already solved

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]

Recovering When a Rebase Goes Wrong

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 badly
git rebase --abort

# Rebase finished, but the result is wrong
git reflog show feature          # every position the branch has held
git 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]

The Golden Rule of Git Rebase

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]

A Team Policy for Rebase and Merge

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.

A Daily Git Rebase Workflow

This is the routine I'd suggest. The config is a one-time setup.

bash
# One-time setup
git config --global rebase.autoSquash true
git config --global rebase.updateRefs true
git config --global rerere.enabled true
git config --global push.useForceIfIncludes true

# Start of the day: catch up with main
git fetch origin
git rebase origin/main

# While working: commit small, and point fixes at their target
git commit -m "Add orders endpoint"
git commit --fixup=":/^Add orders table"

# Before asking for review: tidy, then push safely
git rebase -i origin/main
git push --force-with-lease

Key Takeaways

  • 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.

Sources

  1. [1]Git Branching - Rebasing · Pro Git, Scott Chacon and Ben Straub
  2. [2]git-rebase Documentation · Git
  3. [3]git-commit Documentation · Git
  4. [4]git-rerere Documentation · Git
  5. [5]git-reflog Documentation · Git
  6. [6]git-push Documentation · Git
  7. [7]About merge methods on GitHub · GitHub Docs

Checked against these sources on

Related Articles