Lesson 05 intermediate

Git Merging

How git merge combines branches, fast-forward versus three-way merges, why and when conflicts happen, reading conflict markers with zdiff3, resolving and finishing safely with git add --resolved from Git 2.56, aborting a merge and squash merges.

Branches are only useful if their work comes back together. Merging takes the commits of one branch and integrates them into another. Most merges are automatic; the interesting part is understanding what Git does, and staying calm when it asks you to resolve a conflict.

Merging a branch

You always merge into the branch you are on. To bring feature/search into main:

$ git switch main
$ git merge feature/search

What happens next depends on the shape of the history.

Fast-forward merge

If main has not moved since the feature branch was created, there is nothing to combine. Git simply moves the main pointer forward to the tip of the feature branch:

before:  a1f3 <- 5d1e            (main)
                    \
                     c42d <- e71b (feature/search)

after:   a1f3 <- 5d1e <- c42d <- e71b (main, feature/search)
$ git merge feature/search
Updating 5d1e0a2..e71b3a0
Fast-forward
 search.js | 12 ++++++++++++
 1 file changed, 12 insertions(+)

No new commit is created and history stays a straight line.

Three-way merge

If both branches got new commits, Git finds their merge base (the last commit they share), compares each branch with it and combines both sets of changes into a new merge commit with two parents:

          c42d <- e71b        (feature/search)
         /              \
  5d1e <- 7aa0 <- 90bd <- m3f1 (main, merge commit)
$ git merge feature/search
Merge made by the 'ort' strategy.
 search.js | 12 ++++++++++++
 1 file changed, 12 insertions(+)
$ git log --oneline --graph -5
*   m3f1c20 (HEAD -> main) Merge branch 'feature/search'
|\
| * e71b3a0 Rank search results by date
| * c42d9e1 Add search stub
* | 90bd114 Bump Node.js to 24
|/
* 5d1e0a2 Add README and API entry point

ort is Git’s default merge strategy since version 2.34. Git 2.56 also made finding the merge base much faster in large repositories with many branches.

You can control the shape:

OptionEffect
--ff-onlyMerge only if a fast-forward is possible, otherwise fail
--no-ffAlways create a merge commit, even when fast-forward is possible
--squashStage the combined changes without committing or recording a merge

--no-ff keeps a visible “this feature was merged here” commit, which some teams like for reading history. --ff-only is a good setting for git pull when you never commit directly to main.

Why conflicts happen

A conflict happens when both branches changed the same lines of the same file differently, or one branch edited a file the other deleted. Git cannot know which version is right, so it stops and asks you.

Imagine main changed the port to 8081 while feature/search changed it to 9090:

$ git merge feature/search
Auto-merging server.js
CONFLICT (content): Merge conflict in server.js
Automatic merge failed; fix conflicts and then commit the result.
$ git status -s
UU server.js

UU means “unmerged, changed on both sides”. Every other file was merged and staged automatically.

Reading conflict markers

Open the file and you find the conflicting part wrapped in markers. With merge.conflictStyle set to zdiff3 (lesson 2), Git also shows what the line looked like before either change, which makes the right answer much easier to see:

<<<<<<< HEAD
const port = 8081;
||||||| merge base
const port = 8080;
=======
const port = 9090;
>>>>>>> feature/search
  • From <<<<<<< HEAD to the line of pipes: your branch (main).
  • From the line of pipes to =======: the common ancestor, how the lines looked before either change.
  • From ======= to >>>>>>>: the branch being merged.

Here the ancestor shows that both sides changed 8080. Talk to the author of the feature if needed, decide on the correct value, and edit the file so it contains only the final code, with every marker removed:

const port = 9090;

Finishing the merge

Mark the file as resolved by staging it, then commit:

$ git add server.js
$ git commit                 # Git prepares a "Merge branch ..." message

Git 2.56 added a safer way to do the staging step. git add --resolved stages only the files that were in conflict, and first checks them for leftover conflict markers. If it finds any, it stages nothing and tells you which files still need work:

$ git add --resolved
$ git commit

This prevents a classic accident: git add . happily stages a file that still contains <<<<<<< lines, and broken code gets committed. --resolved ignores files that were never in conflict and cannot be combined with -u or -A.

Tip: git diff during a conflict shows only the unresolved parts. git diff --name-only --diff-filter=U lists the files still in conflict.

Getting out of a merge

If the conflict is bigger than expected or you merged the wrong branch, go back to exactly where you were before:

$ git merge --abort

You can also take one whole side of a file without editing it:

$ git checkout --ours server.js     # keep main's version
$ git checkout --theirs server.js   # keep the incoming branch's version

Remembering resolutions with rerere

If you set rerere.enabled true (lesson 2), Git records how you resolved each conflict. When the same conflict appears again, for example while re-merging or rebasing, Git resolves it for you the same way. You still review and stage the result.

Squash merges

git merge --squash feature/search stages all the changes of the branch as one set, without a merge commit, and you commit them yourself as a single commit. Hosting services offer the same as “Squash and merge” on pull requests. It keeps main tidy, one commit per feature, at the cost of losing the individual commits of the branch. After a squash merge, git branch -d reports the branch as unmerged, because its commits are not in main; delete it with -D.

Quick reference

TaskCommand
Merge a branch into the current onegit merge <branch>
Only if fast-forwardgit merge --ff-only <branch>
Always create a merge commitgit merge --no-ff <branch>
Combine into one staged changegit merge --squash <branch>
List files in conflictgit diff --name-only --diff-filter=U
Stage resolved files safely (2.56)git add --resolved
Cancel the mergegit merge --abort
Take one side of a filegit checkout --ours / --theirs <file>

Exercise

main has not received any commits since you created feature/search. What does git merge feature/search on main do?

  1. Moves main forward to the tip of feature/search without a new commit
  2. Creates a merge commit with two parents
  3. Copies the commits with new IDs on top of main
  4. Stops with a conflict because the branches differ
Show answer

Answer: A. When the target branch is an ancestor of the incoming branch, Git fast-forwards: it only moves the pointer. A merge commit is created only for diverged histories or with –no-ff.

Exercise

You fixed two of the three conflicted files and run git add –resolved. One file still contains a <<<<<<< marker. What happens?

  1. Git stages the two fixed files and skips the third
  2. Git deletes the markers automatically and stages everything
  3. Git commits the merge with the markers in place
  4. Git reports the file with leftover markers and stages none of the conflicted files
Show answer

Answer: D. git add –resolved (Git 2.56) is all or nothing: it checks every conflicted file for markers before staging, and if any remain it leaves the index unchanged so you cannot commit a half-resolved merge.

Exercise

Halfway through a large conflict you realise you merged the wrong branch. How do you return to the state before the merge?

  1. git reset –hard origin/main
  2. git merge –abort
  3. Delete the conflicted files and run git commit
  4. git revert HEAD
Show answer

Answer: B. git merge –abort throws away the merge in progress and restores the branch and working tree to how they were before you ran git merge. git revert works on finished commits, not on a merge in progress.

Key takeaways

  • You merge into the current branch; Git fast-forwards when possible and creates a merge commit when histories diverged.
  • Conflicts mean both sides changed the same lines; Git merges everything else automatically.
  • zdiff3 conflict style shows the original lines between the two versions, which makes decisions easier.
  • Remove every marker, stage the file (or use git add --resolved from Git 2.56) and commit.
  • git merge --abort is the emergency exit; --squash turns a branch into one commit.

FAQ

Are merge conflicts a sign that something went wrong?

No. They are normal when two people work on the same area. Small, short-lived branches and frequent merges from main keep them small and rare.

What is the difference between merge and rebase?

Both integrate changes. Merge keeps history as it happened and adds a merge commit. Rebase rewrites your branch’s commits on top of the other branch for a straight history. Lesson 6 compares them in detail.

Can I use a graphical tool to resolve conflicts?

Yes. VS Code, JetBrains IDEs and many others show both sides with buttons to accept either. Run git mergetool to open the one configured in merge.tool. The result is the same: a file without markers that you stage.

Why does Git say “refusing to merge unrelated histories”?

The two branches share no common commit, often because a repository was created on the server with a README and locally with git init. If you really want to join them, add --allow-unrelated-histories once.

Should my team use squash merges?

It depends on taste. Squash keeps main to one commit per pull request, which is easy to read and revert. Regular merges keep every commit, which helps git bisect and tells the detailed story. Pick one rule and enforce it in the repository settings.

↑ ↓ navigate Enter open Esc close