Rebase vs. Merge: The Team Policy That Ends The Argument Forever

The rebase-vs-merge argument is one of those discussions that recurs in every team I have worked on, sometimes weekly. Engineers learn it as a religion, get strong opinions, and bring those opinions to a new team where the old policy does not apply. The actual question — “what should the history of main look like a year from now?” — never gets asked.

The history is a tool, not a record. It exists to help future you bisect a regression, audit a security commit, or understand why a specific line was added. Nobody benefits from a graph that looks like a subway map. Nobody benefits from squashing six independent fixes into one “wip” commit either. There is a small set of rules that gives you a useful history without a holy war, and this post is that policy.

The policy in one sentence

Rebase your feature branch onto the latest main while you work, and merge it into main as a single squashed commit when you are done. Use a true merge commit only for branches that represent a meaningful inflection point — releases, large refactors that need atomic revert, or topic branches that several people contributed to.

That is the rule. Everything below is the why and the edge cases.

Why rebase the feature branch

A feature branch in flight has two failure modes if you do not keep it current with main.

Drift. Two days into your branch, somebody on the team merges a refactor that renames a function you call. The next time you git pull your branch, you have textual conflicts you didn’t expect — and they are the other person’s conflicts, not yours. Catching that on day two is cheap. Catching it the day before merge is expensive because you have to retest everything you have done since.

Test flakiness on top of stale code. CI passes on your branch, but only because your branch is missing a fix that landed in main last week. The merge button goes green, the merge happens, and main is broken because the combination of your code and the missing fix interact badly.

# On your branch
git fetch origin
git rebase origin/main
# Resolve conflicts as they appear, in small chunks. CI runs again.
git push --force-with-lease

--force-with-lease is the right form: it refuses to overwrite the remote branch if somebody else has pushed to it (which would otherwise destroy their work). Plain --force is the foot-gun version.

For a long-lived branch, rebase daily. The conflicts compound super-linearly the longer you wait.

Why squash on merge

When the feature is done, the question is “what should main’s history look like?” And the answer for most features is “one commit per logical change.”

If your feature was implemented with twelve small commits — fix typo, wip, PR feedback: rename variable, fix flaky test — that history is interesting only to you, only this week, and only if you have not finished yet. It will be noise to future readers. Squashing collapses it into one commit with the PR description as the message.

$ git log --oneline -5
a1b2c3d  feat(orders): allow split shipping per line item (#1234)
e4f5g6h  fix(auth): refresh token rotation race condition (#1233)
i7j8k9l  chore(ci): bump GitHub Actions runner to 22.04 (#1232)
m0n1o2p  refactor(billing): extract invoice numbering into module (#1231)

Each commit is one PR, one change, one revert button. git bisect works because each commit is self-contained and tested. git blame points at the PR, not at “wip 7.” That is the win.

GitHub’s “Squash and merge” button does this for you. So does git merge --squash. Configure your repo so it is the default for the merge button (Settings → General → Pull Requests → “Allow squash merging” → set “Default to PR title and description”).

When NOT to squash

Three exceptions where a true merge or a series of separate commits is correct.

Releases. When main merges into production, you want the merge commit to be visible — it is the boundary between “candidate” and “released” code. git log production should show one commit per release, with a tag.

git checkout production
git merge --no-ff main
git tag v1.42.0
git push origin production --tags

--no-ff (no fast-forward) forces a merge commit even if production could fast-forward — that is the point. The merge commit is the inflection.

Large refactors that need atomic revert. If your feature is “extract billing into its own module,” that may be five commits, each of which leaves the codebase in a working state, and which together need to be reverted as a unit if something goes wrong. Merge with --no-ff (or use a merge commit on PR) to preserve those commits but bind them under one merge so a single git revert -m 1 <merge-sha> undoes the whole thing.

Multi-author topic branches. If two people built a feature together with meaningful per-author history, squashing destroys the attribution. Merge with a merge commit and let the individual commits live.

For everything else — the 90% case of “one engineer ships one feature in a week” — squash.

Linear history, with caveats

Some teams enforce strictly linear history (rebase merging instead of squash merging — every commit lands on top, no merge commits). The pitch: git log --oneline is a perfectly straight line, easy to read, easy to bisect.

The cost: each commit on the feature branch lands on main individually, which means each commit has to be a working state on its own. Otherwise git bisect lands on a broken commit and reports a phantom regression. This forces engineers to clean up their commit history obsessively before merge — which is great discipline if your team will actually do it, and a pure waste of energy if they won’t.

Squash merging gives you 80% of the benefit (linear-looking history of one-commit-per-PR) at 20% of the cost. I recommend it for most teams. Reserve linear-with-multiple-commits-per-PR for teams that already write small, atomic commits naturally.

The four moves you actually need

Forget the long blog posts about Git internals. Day-to-day, four commands cover almost everything.

# 1. Sync your branch with main, replaying your work on top.
git fetch origin
git rebase origin/main

# 2. Tidy the last few commits of your branch (squash, reword, reorder).
git rebase -i HEAD~5

# 3. Push your re-written branch back, safely.
git push --force-with-lease

# 4. When done, merge via the PR UI with "Squash and merge".
#    (Or locally: git merge --squash <branch> && git commit)

If you find yourself reaching for cherry-pick, revert, reflog, or filter-branch, you are doing something rare. Pause and Google — those are recovery tools, not daily ones.

Conflicts: the right way to resolve them

The single best thing you can do for conflicts is git config --global merge.conflictstyle zdiff3. This tells Git to show three sides during conflict resolution: yours, theirs, and the original common ancestor. That third side is gold — it shows you what the code was before either of you touched it, which makes “did we both refactor this?” obvious.

<<<<<<< HEAD
return computeTotal(lineItems);
||||||| ancestor
return total(lineItems);
=======
return total(lineItems, taxRate);
>>>>>>> feature-branch

You can see immediately: somebody on main renamed total to computeTotal; you on the branch added a taxRate argument. The resolution is computeTotal(lineItems, taxRate). Without zdiff3, you would only see the first and third sections and would have to guess.

Pair that with a three-way merge tool (git mergetool with vimdiff, VS Code’s built-in, or Beyond Compare) and conflict resolution stops being scary.

What to do about old commits already pushed

The most common failure mode in adopting “rebase your feature branch” is rebasing a branch other people already based their work on. You force-push, their checkout breaks, they get angry.

Rule: never rebase a branch other people are working on. Once you have shared a branch (someone else has pulled it), it is public history. Treat it the same way you would main — only add commits, never rewrite them.

If you absolutely must rewrite shared history (legal redaction, leaked secret), coordinate over chat: “I’m about to rewrite branch X, please don’t push.” After the rewrite, everyone with a local copy needs to git fetch && git reset --hard origin/X.

For long-lived shared branches (release branches, integration branches), use merge commits. Rebase is a private-branch tool.

What CI should enforce

A few protections that make the policy stick:

• main is protected. No direct pushes; PRs only.
• Required status checks before merge. If CI fails, the merge button is locked.
• Required up-to-date branch. GitHub’s “Require branches to be up to date before merging” forces a rebase against the latest main right before merge — closes the race where two PRs pass CI and merge into a broken state.
• Squash-merge is the default. Disable other options in repo settings, or document explicitly when each is allowed.
• Linear history is required on main. Prevents the occasional accidental fast-forward of a feature branch into main instead of squashing.

These five settings turn “we have a policy” into “the policy is enforced even when somebody is in a hurry.”

The takeaway

The rebase-vs-merge debate dissolves once you ask the right question: what should main look like in a year? The answer is “one commit per logical change, in order, each independently revertable.” Squash-merging feature branches achieves that. Rebasing your branch onto main while you work keeps you out of conflict swamps.

Use a true merge only at meaningful boundaries — releases, atomic refactors, multi-author topics. Configure CI to enforce the policy. Pick --force-with-lease over --force. Turn on merge.conflictstyle = zdiff3.

The hours your team will save are not in the merging itself — they are in the future debugging sessions where the history reads cleanly and the right commit is the one you find on the second git bisect step.

---

A note from Yojji

The kind of process discipline that keeps a long-lived codebase legible — repo settings, merge policy, CI gates that match the team’s review style — is the kind of unglamorous engineering hygiene that compounds. It is the kind of foundation Yojji’s teams put in place for the products they ship.

Yojji is an international custom software development company founded in 2016, with teams across Europe, the US, and the UK. They specialize in the JavaScript ecosystem (React, Node.js, TypeScript), cloud platforms (AWS, Azure, GCP), and full-cycle product engineering — including the development practices that decide whether a codebase still feels good to work in two years on.