Concept · Merging & history
Merge vs rebase
Keep the true shape of history, or replay your commits on top for a straight line — and never rebase shared commits.
Your branch is behind main. There are two ways to bring in the new commits.
A ─ B ─ E ─ F ← main
└ C ─ D ← featureMerge (git merge main, run on feature) adds a merge commit that joins the two histories:
A ─ B ─ E ─ F
└ C ─ D ─ M ← featureRebase (git rebase main, run on feature) replays your commits on top of the new main, creating new commits C' and D':
A ─ B ─ E ─ F ─ C' ─ D' ← featureTrade-offs
| Merge | Rebase | |
|---|---|---|
| History | True shape: what happened, when | Straight line, as if you'd started from the latest main |
| Commits | Unchanged; hashes stay the same | Rewritten: new hashes (see the object model) |
| Conflicts | Resolved once, in the merge commit | Possibly once per replayed commit |
| Safe on shared branches | Yes | No |
Reading git log and bisecting | Noisier | Cleaner |
The golden rule
Never rebase commits that other people have based work on.
Rebasing replaces commits with new ones. If a teammate already has the old C and D, their history and yours have now diverged, and the next pull brings back duplicates or conflicts. Rebasing your own unpushed commits, or your own feature branch that nobody else uses, is fine.
When you do have to push a rebased branch, use
git push --force-with-leaseThis refuses to overwrite the remote if someone pushed to it after your last fetch. Plain --force silently throws their work away.
A common combination
- Rebase locally to keep your branch current and tidy.
git rebase -i mainlets you squash fixups, reword messages and reorder commits before review. - Merge into
main, via the platform's merge or squash button, somainitself is never rewritten. - Set
git config --global pull.rebase truesogit pullon your feature branch rebases instead of adding "Merge branch 'main'" noise.
Nearly any rebase can be undone: the reflog has the pre-rebase commits. How a team combines these is a workflow decision, so agree on one.