One History, Two Outcomes
main: A --- B --- C --- D
\
feature: E --- F
Both approaches integrate feature into main, but the resulting history is entirely different:
# merge: keep the fork, create merge commit G
git checkout main
git merge feature
# rebase: replay E, F onto D as E', F', then fast-forward
git checkout feature
git rebase main
git checkout main
git merge feature
merge: A --- B --- C --- D -------- G
\ /
feature: E ------- F
rebase: A --- B --- C --- D --- E' --- F'
E' and F' have the same content as E and F but completely new hashes — commits are copied and rebuilt, not moved. Every later difference follows from this.
The Differences in One Table
| Dimension | merge | rebase |
|---|---|---|
| History shape | fork + merge commit | straight line |
| Commit hashes | unchanged | all rewritten |
| Shared-branch safety | ✅ | ❌ |
| Conflict resolution | once | repeated per commit |
| Mistake recovery | --abort suffices |
needs reflog |
| Code review experience | fair | better |
git bisect |
slightly noisy | more precise |
| Records integration time | ✅ merge commit | ❌ lost |
Two rows deserve their own explanation.
Merge pays in noise. Syncing main back into a feature branch repeatedly piles up "Merge branch 'main' into feature" commits, makes git log messy, and adds intermediate nodes to git bisect. --first-parent recovers the mainline view, but "which lines did this feature change" still requires judging the diff range.
Rebase pays in irreversible rewriting. Once hashes change, every reference to the old commits breaks — teammates' branches, CI caches, linked PRs, submodule pointers. Conflicts also are not solved once: every replayed commit can conflict again. Rebase onto a main that moved far ahead and six commits mean six consecutive conflict resolutions, which is what makes rebase painful.
The Golden Rule: Never Rebase a Shared Branch
Never rebase commits that have already been pushed to a shared repository.
The mechanism is simple. Teammates already pulled E and F; after your rebase the remote holds E' and F'. Their next pull sees two distinct commit lines and merges both, leaving duplicated commits with identical content. Repairing it requires a force push, which then overwrites whatever they pushed after.
That is why "not yet pushed" is the safety line: with no second holder of those hashes, rewriting has no external effect.
If it already went wrong, the reflog is the safety net:
git reflog
# find the hash before the operation, e.g. abc1234
git reset --hard abc1234
The reflog keeps entries for 30 days by default; if the commits were garbage-collected or never referenced by a branch, recovery is harder. A deleted branch is recoverable too with git branch <name> <hash>.
Three Workflows You Can Copy
Solo / local tidying: commit freely, clean up before pushing:
git commit -m "wip: scaffold"
git commit -m "wip: core logic"
git rebase -i HEAD~2 # squash into one clean commit
git push
Interactive rebase actions: pick keep, reword edit message, edit change content, squash merge, fixup merge and discard the message, drop delete.
Feature branch (recommended combination): rebase onto the latest main before integrating, then fast-forward main:
git fetch origin
git rebase origin/main
git checkout main
git pull --ff-only
git merge feature
git push
This holds only while nobody else uses the feature branch. Once it is pushed for review and someone builds on it, that route is closed.
Conservative teams / audit needs: force a merge commit so "when it landed" stays visible:
git checkout main
git pull
git merge --no-ff feature
git push
--no-ff creates a merge commit even when fast-forward is possible, so releases and rollbacks can locate the feature boundary at a glance.
Conflict work follows the same structure: merge solves it once (git add, then git commit); rebase repeats per commit (git add, then git rebase --continue), with git rebase --abort as the escape hatch.
Decision: Merge Public History, Rebase Private History
| Scenario | Recommendation |
|---|---|
| Tidying local WIP commits | rebase -i (squash + reword) |
| Solo project | either; rebase is cleaner |
| Unpushed feature branch into main | rebase onto latest, then merge |
| Conservative team / audit | merge --no-ff |
| Already-pushed shared commits | never rebase; merge |
| Open-source contribution | follow upstream convention, usually rebase |
In one line: merge public history, rebase private history. The test is not which history looks nicer, but whether anyone else depends on those hashes. If yes, merge; if no, tidy freely.
For daily commands see the Git command cheat sheet.
Reproducible Results
A throwaway repo reproduces both shapes in two minutes:
git init demo && cd demo && git config user.email t@t && git config user.name t
echo 1 > f && git add . && git commit -qm c1
git checkout -b feature && echo 2 > g && git add . && git commit -qm f1
git checkout master && echo 3 > h && git add . && git commit -qm c2
git merge --no-ff feature -m merge
git log --oneline --graph --all
* 3fd7cf7 merge
|\
| * 8731bd3 f1
* | 51c7533 c2
|/
* b4cb9fb c1
Reset and rebase instead (git reset --hard HEAD~1, then git rebase feature):
* 7ceea61 c2
* 8731bd3 f1
* b4cb9fb c1
c2 now sits after f1 and the merge node is gone — direct evidence that merge preserves history while rebase rewrites it.