Part IV: Chapter 4.9

Rebase vs Merge

Same changes. Different history.

Both merge and rebase integrate the same work. The difference is entirely in the shape of the commit graph they leave behind — and that shape has real consequences for how readable your project history is.

The Graph Difference

Start with the diverged state, then click "After integration" to see what each strategy produces.

git merge feature
ABCDEmainfeature HEAD
git rebase main → git merge (ff)
ABCDEmainfeature HEAD

When to Merge

  • ✓Integrating a completed feature into main. The merge commit documents exactly when the feature landed and from where.
  • ✓Shared/public branches. Rebase rewrites history; if others have already pulled those commits, you'll cause divergence on their machines.
  • ✓When you want a faithful record. Merge preserves the actual timeline — useful for audit trails and understanding the true sequence of events.

When to Rebase

  • ✓Keeping a local feature branch up to date. Before opening a PR, rebase onto main so your branch applies cleanly without a merge commit.
  • ✓Cleaning up messy WIP commits. Squash, reword, and drop commits before sharing them — keep public history clean.
  • ✓Private/local branches only. The golden rule: never rebase commits already pushed to a shared remote branch.

The Golden Rule of Rebase

Rebase rewrites commit hashes. If you rebase commits that someone else has already pulled, their history will diverge from yours — they'll have the old commits, you'll have the rewritten ones. Reconciling this is painful.

Terminal
$# Safe: rebasing a local branch before pushing
$git switch feature
$git rebase main
$git push origin feature # first push — safe
$
$# DANGEROUS: rebasing after the branch is shared
$git rebase main # rewrites hashes
$git push --force origin feature # now others are diverged
# Their git pull will result in conflicts or duplicate commits
$
$# Safe alternative for a shared branch: merge instead
$git merge main # adds a merge commit, no hash rewrites