git merge

Three-way merge. Fast-forward when it can. A merge commit when it can't.

🎯 What & why

Combine the histories of two branches. If the destination branch's tip is an ancestor of the source's, you get a fast-forward. Otherwise, Git makes a merge commit with two parents.

🧠 Mental model

Merge runs a three-way merge: it finds the merge base (the common ancestor) and computes the union of changes from both sides. Conflicts arise where both sides changed the same lines or one side changed lines the other deleted. The new commit's tree is the merged result; its parents are the two tips.

🛠️ Synopsis

git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
          [--no-verify] [-s <strategy>] [-X <option>] [-S[<keyid>]]
          [--[no-]allow-unrelated-histories] [--[no-]rerere-autoupdate]
          [-m <msg>] [-F <file>] [<commit>...]
git merge (--continue | --abort | --quit)

🎚️ Switches & options

Flag	What it does
`--no-ff`	Always create a merge commit, even if fast-forward is possible. Preserves topology.
`--ff-only`	Refuse if a fast-forward isn't possible.
`--squash`	Apply the merge as a single commit on the current branch (no merge commit).
`-s <strategy>`	Pick a merge strategy (`ort` is default in modern Git, `recursive`, `octopus`).
`-X <option>`	Strategy option, e.g. `-X ours` or `-X theirs` for conflict bias.
`--abort`	Bail out of an in-progress merge.
`--continue`	Resume after resolving conflicts.

💡 Use cases

Bringing a feature branch into a long-lived branch.
Periodic syncs of a release branch into main.
Squashing a tidy single commit out of a messy feature branch.

🧪 Examples

Merge a feature branch into main.

$ git switch main
$ git merge feature/login

Force a merge commit even when fast-forward is possible.

$ git merge --no-ff feature/login

Squash-merge: one commit on main, no merge object.

$ git merge --squash feature/login
$ git commit -m 'feat: login (squashed)'

Bail out mid-conflict.

$ git merge --abort

🎓 Recommendations

On main, prefer --no-ff if you want the topology to remember the feature branch existed. Otherwise fast-forward is fine.
When pulling in long-running branches, do a trial merge with git merge --no-commit --no-ff to inspect first.
When conflicts hit, git status is your friend — it lists the unmerged paths and the resolution path.

🪤 Common pitfalls

--squash does not create a merge commit. The merged branch's history is not recorded as a parent. Don't use it if you care about merge tracking.
Once you have conflicts, git status says --continue is the next step. Don't try to commit directly without resolving.
Merge with -X ours favors your side on conflicts — easy to misuse.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.