Rebase vs Merge

Rebase vs merge: shape and intent

Both rebase and merge integrate work from one branch into another. The difference is what they do to history. Merge creates a new commit with two parents that joins the histories at a Y-junction; both lines remain visible in the graph. Rebase replays the source branch's commits as new commits on top of the target's tip; the result is a single linear chain with no merge commit. Same content; very different shape.

The pragmatic decision tree. Use merge when the divergence is meaningful: integrating a long-running release branch, marking the completion of a feature as a unit of work, preserving the audit trail of "this came in from where" for compliance. Use rebase when the divergence is incidental — short-lived feature branches whose commits would clutter main with noise like "merge of main into feature/x." For most product teams shipping daily, rebase wins for feature branches because main reads as a single sequence of features rather than a tangle.

The team-policy form: pick one of three. (a) Linear history — every PR rebases onto main and merges fast-forward; main is one chain. (b) Always merge — every PR creates a merge commit even when fast-forward is possible (--no-ff); main has visible feature units. (c) Squash on merge — every PR's commits collapse into one commit on main; main is one commit per PR, regardless of internal structure. Each is internally consistent. Mixing them is the actual problem.

Two practical commands. git rebase main from a feature branch replays your local commits onto main's current tip. Conflicts pause the rebase like in interactive mode; resolve, git rebase --continue. git rebase --onto <new-base> <old-base> <branch> moves a branch from one base to another, useful when you branched off the wrong place originally.

Code

Two integration shapes·bash

# Rebase feature onto current main:
git switch feature/x
git fetch origin
git rebase origin/main

# Result: feature/x's commits sit linearly on top of origin/main.

# Merge instead:
git switch main
git merge feature/x          # FF if possible, three-way otherwise
git merge --no-ff feature/x  # always create a merge commit

Rebase --onto for surgical re-parenting·bash

# You branched feature/email-templates off feature/auth,
# but feature/auth is going to be discarded. You want
# email-templates to live on top of main instead.

git rebase --onto main feature/auth feature/email-templates

# Reads as: "replay feature/email-templates' commits since
# feature/auth onto main, replacing the old base."

Exercise

Set up two scratch repos starting from the same baseline. In one, finish a feature branch and integrate via git merge --no-ff. In the other, integrate via git rebase main followed by fast-forward merge. Run git log --oneline --graph --all on each. Compare shapes. Decide which one you would prefer to read in six months and write one sentence on why.

Rebase vs merge: shape and intent

Code

External links

Exercise

Progress

Comments 0