Rebase or merge: integrating a branch

What it is

git merge combines two lines of development with a merge commit that has two parents; the history shows when the branch diverged and when it came back. git rebase replays a branch's commits on top of another commit, producing new commit objects and a linear history; the original commits are abandoned.

Why it matters

Linear history is easier to read and bisect; merge history is honest about parallel work. The choice matters most for shared branches: Pro Git states the rule plainly – do not rebase commits that exist outside your repository and that people may have based work on, because their history then diverges from yours.

How to apply

• Rebase your own unpublished topic branch onto the current integration branch before opening a review, so that the diff is against fresh code.
• Merge (or squash-merge) into the integration branch through the review tool; keep the team's chosen style consistent.
• Use git pull --rebase for local integration to avoid noisy "merge branch main into main" commits.
• After a rebase, force-push only your own branch, and prefer --force-with-lease so you do not overwrite someone else's push.

Pitfalls

Rebasing a branch that a colleague has checked out creates duplicate commits and conflicts for them. Conflict resolution during a long rebase must be repeated per commit; squashing first reduces that. Rewriting history destroys signatures on the rewritten commits.