Most developers run git pull dozens of times a week without thinking about it. And most of the time, it works.
Then one day you open a PR and the reviewer says "can you clean up the merge commits?" You look at your branch and see three "Merge branch 'main' into feature/login" commits scattered through history. The feature itself is 5 commits. The log is a mess.
That mess comes from one decision: using git pull instead of git pull --rebase.
Here's what's actually happening, and why the rebase variant produces cleaner history for teams.
The setup: diverged history
You're working on feature/login. You commit two changes locally (X, Y). Meanwhile, your teammate pushes two commits to main (C, D).
Your branch and main have now diverged. Neither is a strict superset of the other. Git needs to reconcile them when you pull.
Shared history: A → B
Your local: A → B → X → Y (you added X, Y)
Remote main: A → B → C → D (teammate added C, D)
Git has two strategies for this reconciliation.
Strategy 1: git pull (merge)
A plain git pull creates a merge commit that joins your local history with the remote. Your commits and the remote's commits both appear in the log, connected by a merge node.
The git log reads:
M Merge branch 'main' into feature/login
D fix: timeout on slow connections
Y feat: client-side validation
C chore: upgrade eslint
X feat: login form
B (shared)
A (shared)
This is honest history — it records exactly what happened: parallel development that was joined at a specific point.
But it's also noisy history — the merge commit has no meaningful changes, and the log interleaves commits that weren't conceptually related.
Strategy 2: git pull --rebase
With --rebase, Git takes a different approach. It:
- Temporarily sets aside your local commits (
X,Y) - Fast-forwards your branch to the tip of the remote (
D) - Replays your commits on top, one by one, creating new commits (
X',Y')
The git log reads:
Y' feat: client-side validation
X' feat: login form
D fix: timeout on slow connections
C chore: upgrade eslint
B (shared)
A (shared)
Linear. No merge commit. Your work appears as if you'd started from the latest main in the first place.
Why linear history matters
When your team reviews your PR, linear history means:
The diff is cleaner. GitHub/GitLab can show a straightforward diff of what your feature adds. No merge commits cluttering the view.
The PR itself applies cleanly. When a reviewer merges your PR, it becomes a simple fast-forward on main — or a clean --no-ff if your team uses that policy. No extra merge-of-merges.
History reads like a changelog. git log --oneline main reads like a list of features shipped, one per line, in order. That's what main should look like.
Compare that to a git log full of "Merge branch 'main' into feature/login" commits — it tells you when people synchronized their branches, not what was actually built.
The commits X' and Y' are new commits
This is the subtle part that trips people up.
With rebase, X' has a different hash than X. It has the same diff — same changes to the same files — but because its parent is now D instead of B, Git considers it a new commit.
This matters for one reason: rebase rewrites history.
The golden rule of rebase
Never rebase commits that other people may have pulled.
If you rebase commits that a teammate already pulled, their local copy has the old hashes and your copy has the new hashes. When they pull again, Git sees two different sets of "the same" commits and produces duplicates, conflicts, or confusion.
The safe pattern:
- Your local, unpushed branch: rebase freely
-
Your pushed feature branch, if you're the only one on it: rebase +
git push --force-with-lease -
Shared branches like
mainordevelop: never rebase ## Making rebase your default
If you want to use rebase for pulls without typing --rebase every time:
git config --global pull.rebase true
Now every git pull is actually git pull --rebase. Most teams that care about clean history do this. You can always override with git pull --no-rebase if you want a specific merge.
For even stronger safety, combine it with:
git config --global rebase.autoStash true
This auto-stashes your uncommitted changes before the rebase and pops them back after. Saves you from "cannot rebase: you have unstaged changes" errors.
When git pull (merge) is actually correct
There are cases where a merge is the right choice:
Long-lived feature branches. If your feature branch has been alive for weeks and multiple people have pushed to it, rebasing it rewrites history others depend on. Use merge.
Explicit integration points. Some teams like the merge commit to mark "we integrated main into feature at this point" as a deliberate milestone. That's fine — it's a conscious choice.
When you want the team to see what happened. If a feature took three sprints and main moved a lot during that time, the merge commits show that context. For most features, you don't need that — but for big ones, sometimes you do.
The mindset shift
Pull is a boring command that most developers run on autopilot. But behind that one word are two very different operations:
- Merge pull preserves history, creating merge commits. History reflects what happened.
-
Rebase pull rewrites history, producing a linear log. History reflects the intent.
For daily work on short-lived feature branches, the rebase approach almost always produces a better result — for your PR, for your reviewer, for whoever reads
git login six months.
Switch your default. Learn the golden rule. Don't look back.
This post is adapted from Git in Depth: From Solo Developer to Engineering Teams, a 658-page book covering Git the way it's actually used in real engineering teams.
