Recap — When to Rebase, When to Merge

# When to Rebase, When to Merge Both rebase and merge integrate changes between branches. They produce different history shapes; teams disagree on which is better. Understand both; choose based on context. ## Merge — preserve history ```bash git switch feature git merge main # bring main's changes into feature ``` Creates a merge commit: ``` main: A → B → C feature: \ → D → E ↓ After merge: A → B → C → M (M = merge commit; parents: C and E) \ ↗ D → E ``` Pros: - Non-destructive (original commits intact). - History shows branching reality. - Safe for shared branches. Cons: - "Merge commits" can clutter history. - Hard to bisect (merge commits don't represent atomic changes). ## Rebase — rewrite history ```bash git switch feature git rebase main # replay feature's commits on top of main ``` ``` Before: main: A → B → C feature: \ → D → E After rebase: main: A → B → C feature: \ → D' → E' (new commits with different SHAs) ``` The commits D and E are REPLAYED with C as their new parent. New SHAs (D', E') because parent changed. Pros: - Linear history (easier to read). - No merge commits cluttering. - Each commit on feature now has main's latest as base. Cons: - DESTRUCTIVE: original commits replaced with new ones. - Can cause confusion if pushed to shared branches. - Conflicts may surface for each replayed commit. ## The golden rule **Never rebase commits that have been pushed and others might be using.** If you've shared the commits, rewriting them means others' work is based on commits that no longer exist. Same problem as force-push. Rebase is fine for: - Local commits (not yet pushed). - Your own feature branches (after coordinating). - "Cleaning up" before pushing. Merge is required for: - Anything on `main` or shared branches. - Public/open-source contributions. ## When to use which ### Use rebase when: - Your feature branch needs main's latest, and you want a clean linear history. - Before opening a PR, to integrate feedback cleanly. - To squash WIP commits into a few logical ones. ### Use merge when: - Bringing a feature branch into main (the integration moment). - Preserving the historical context of "this was a branch". - The commits have been shared and rebasing would disrupt collaborators. ## Resolving rebase conflicts Unlike merge (one conflict event), rebase replays each commit sequentially. You may resolve conflicts per commit: ```bash git rebase main # Conflict in commit D # Edit files to resolve git add file.txt git rebase --continue # Conflict in commit E # Edit files git add file.txt git rebase --continue # Done ``` To abort midway: ```bash git rebase --abort # restore pre-rebase state ``` Skipping a commit: ```bash git rebase --skip # if you decide a commit isn't needed ``` ## Force-push after rebase After rebasing your local branch, the remote's old commits don't match. You need to force-push: ```bash git push --force # dangerous git push --force-with-lease # safer: refuses if remote moved unexpectedly ``` `--force-with-lease` is the SAFE alternative: - Checks that remote is in the state you last fetched. - If someone pushed between your last fetch and your push, refuses (you'd see their work). - Use this by default for force-push. ## Pull with rebase ```bash git pull --rebase # Equivalent to: git fetch; git rebase origin/main ``` Instead of merging the remote's changes (creating a merge commit), rebase your local commits on top of the remote. Result: linear history; your commits appear on top of remote's latest. Set as default: ```bash git config --global pull.rebase true ``` ## Squash merges (the third option) GitHub's "Squash and merge" button takes ALL commits of a PR and combines them into ONE commit on main. ``` feature: D → E → F After "squash and merge": main: A → B → C → S (S contains the combined changes of D + E + F) ``` Pros: - Main has one commit per feature; very clean. - Feature's WIP messy history doesn't appear on main. Cons: - Loses individual commit granularity. - Bisect would only find the squashed commit, not the specific change. Used by many teams: messy on feature branch (commit often, WIP fine); clean on main (one commit per feature). ## Comparison table | Strategy | History shape | Use when | |---|---|---| | Merge (default) | Branching | Default; safe for shared work | | Merge --no-ff | Forced branching | Always show feature branches | | Rebase | Linear | Personal cleanup before sharing | | Squash merge | One commit per PR | Main history kept very clean | | Fast-forward | Linear (no merge commit) | Simple linear cases | ## Team conventions Teams typically pick one style: - **Merge-only**: everything is merged; many merge commits in history. - **Rebase + merge**: rebase locally before pushing; merge into main with --no-ff. - **Squash and merge**: one commit per PR on main; mess