Resolve Git Merge Conflicts with Confidence

You will deliberately create a merge conflict, read the conflict markers, and resolve it correctly. By the end conflicts will feel routine rather than scary, and you will know how to back out safely.

A merge conflict is not an error and it is not Git being broken. It is Git refusing to guess. When two branches change the same lines of the same file in different ways, Git has no rule for which version is "right", only a human knows that. So Git stops the merge, marks the disputed region in the file, and waits for you to decide. Every professional developer hits conflicts weekly; the difference between a beginner and a professional is that the professional has a calm, repeatable procedure. This lab gives you that procedure: reproduce, inspect, read, resolve, verify, and (when needed) abort.

Architecture Overview

Every conflict has the same shape: both branches descend from one common ancestor commit, and each branch modified the same region of a file after that split. During a three-way merge Git compares the ancestor against both branch tips. Regions that only one side touched are merged automatically; regions that both sides touched differently become conflicts.

The practical consequence: conflicts are a function of overlap, not of how long a branch lives or how many commits it has. Two one-commit branches that touch the same line will conflict; two fifty-commit branches that touch different files will merge cleanly.

How It Works

How Git Decides: The Three-Way Merge

When you run git merge feature/api from main, Git does not compare the two branch tips directly. It finds the merge base, the most recent commit reachable from both branches, and performs two diffs: base→ours and base→theirs. You can find the base yourself:

FIND THE MERGE BASE

$ git merge-base main feature/api
3b1f9c2a1e8d0f4b6c7a9e2d5f8b1c3a6e9d0f2a

Three outcomes are then possible per file region:

• Only one side changed it → Git takes that side's version automatically. Most of any merge is this.
• Both sides changed it identically → Git takes one copy; no conflict.
• Both sides changed it differently → conflict; Git writes both versions into the file with markers and waits for you.

A fourth case confuses beginners: if main has not moved since the branch was created, there is nothing to reconcile, and Git just moves the main pointer forward. That is a fast-forward merge, no merge commit, and no possibility of a conflict. Conflicts require both sides to have new commits since the base.

Prevention beats resolution on real teams. Four habits eliminate most conflicts before they happen:

• Keep branches short-lived, days, not weeks. Every day a branch lives, the drift from main grows.
• Rebase or merge from main frequently, resolving five small overlaps over a week beats resolving one giant one at the end.
• Agree on file ownership, if two people are reformatting config.js the same week, that is a communication bug, not a Git problem.
• Avoid drive-by reformatting, a whitespace-only change to a file someone else is editing manufactures conflicts out of nothing.

Environment Setup

You will need: Git and an optional merge tool (VS Code, meld).

Before you begin: conflicts happen when two branches change the same lines; that is normal.

Confirm Git is installed and new enough (anything from the last several years is fine; the commands here need Git 2.23+):

CHECK GIT VERSION

$ git --version
git version 2.46.0

We will work inside a brand-new throwaway repository so nothing real is at risk. That is the right way to practice: make the conflict happen on purpose, in a repo you can delete afterward.

Step-by-Step Execution

git init -b main
git config user.name "Lab User"
git config user.email "[email protected]"

cat > config.js <<'EOF'
// App configuration
const port = 5000;
module.exports = { port };
EOF

git add config.js
git commit -m "Add config.js with default port 5000"

Initialized empty Git repository in /home/you/merge-lab/.git/
[main (root-commit) 3b1f9c2] Add config.js with default port 5000
 1 file changed, 3 insertions(+)
 create mode 100644 config.js

git switch -c feature/api
sed -i.bak 's/port = 5000/port = 3000/' config.js && rm config.js.bak
git commit -am "Use port 3000 for the API"

git switch main
sed -i.bak 's/port = 5000/port = 8080/' config.js && rm config.js.bak
git commit -am "Use port 8080 on main"

$ git log --oneline --graph --all
* 9d2e4a1 (main) Use port 8080 on main
| * 71c0b8f (feature/api) Use port 3000 for the API
|/
* 3b1f9c2 Add config.js with default port 5000

Auto-merging config.js
CONFLICT (content): Merge conflict in config.js
Automatic merge failed; fix conflicts and then commit the result.

$ git status
On branch main
You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Unmerged paths:
  (use "git add <file>..." to mark resolution)
        both modified:   config.js

no changes added to commit (use "git add" to track changes)

<<<<<<< HEAD
const port = 8080;   // your change
=======
const port = 3000;   // their change
>>>>>>> feature/api

// App configuration
const port = process.env.PORT || 8080;
module.exports = { port };

$ git status
On branch main
All conflicts fixed but you are still merging.
  (use "git commit" to conclude merge)

Changes to be committed:
        modified:   config.js

$ git diff --check        # silent = no markers or whitespace errors in uncommitted changes
$ grep -rn '<<<<<<<' . --exclude-dir=.git   # must print nothing
$ git log --oneline --graph
*   7f3ac91 (HEAD -> main) Merge branch 'feature/api'
|\
| * 71c0b8f (feature/api) Use port 3000 for the API
* | 9d2e4a1 Use port 8080 on main
|/
* 3b1f9c2 Add config.js with default port 5000

git reset --hard HEAD~1        # drop the merge commit (never do this if pushed!)
git merge feature/api          # conflict again, on purpose
git status                     # "You have unmerged paths." - we are mid-merge
git merge --abort              # back out cleanly
git status                     # "nothing to commit, working tree clean"

Using a Visual Merge Tool

Hand-editing markers is fine for one hunk in one file. For a conflict spanning many files, a three-pane merge tool (yours / base / theirs, with the result at the bottom) is far faster and far less error-prone. Configure one once:

CONFIGURE VS CODE AS MERGETOOL

git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait --merge "$LOCAL" "$REMOTE" "$BASE" "$MERGED"'

OR CONFIGURE meld

git config --global merge.tool meld

Then, while a merge is conflicted, launch it with git mergetool. Git opens each unmerged file in turn; you save and close each one, and Git stages the resolved versions automatically.

LAUNCH THE MERGE TOOL

$ git mergetool
Merging:
config.js

Normal merge conflict for 'config.js':
  {local}: modified file
  {remote}: modified file
Hit return to start merge resolution tool (vscode):

Common mistake: meld and some other tools leave config.js.orig backup files behind. Disable that with git config --global mergetool.keepBackup false, or at least add *.orig to your .gitignore so backups never get committed.

Conflicts During Rebase and Cherry-Pick

Everything above applies verbatim to two other operations that stop on conflicts: git rebase and git cherry-pick. The mechanics are identical, edit the markers, git add, but two details differ and regularly trip people up.

First, the sides feel backwards. During git rebase main, your commits are being replayed on top of main, so HEAD (the "ours" side of the markers) is main's code, and "theirs" is your own commit being applied. If you instinctively keep the "ours" side thinking it is your work, you will throw your own changes away. Read the actual code, not the labels.

Second, the conflict can strike once per commit. A merge conflicts at most once per run; a rebase of ten overlapping commits can stop ten times. The loop is:

THE REBASE CONFLICT LOOP

git rebase main
# ... CONFLICT: fix markers in the file ...
git add config.js
git rebase --continue        # move on to the next commit; repeat if it stops again
# or give up on the whole rebase:
git rebase --abort           # back to exactly where you started

If you find yourself resolving the same hunk over and over during a long rebase, that is exactly what rerere (from the Troubleshooting section) exists for, enable it once and Git replays your previous resolutions automatically.

Cherry-pick behaves like a single-step rebase: resolve, git add, then git cherry-pick --continue, or bail out with git cherry-pick --abort. Same markers, same tools, same calm.

Progress So Far

Testing & Validation

Status should show a clean tree. diff --check should be silent on uncommitted changes and the grep for marker text should print nothing; together they prove no conflict markers survive anywhere in the tree. Run your tests to confirm the merge is correct, not just conflict-free.

That last point deserves emphasis: a clean merge is not the same as a correct merge. Git only guarantees that no markers remain. It cannot know that keeping port 8080 breaks the integration tests that expect 3000, or that two individually-valid changes contradict each other semantically. This is called a semantic conflict, and the only defense is running the test suite after every merge:

FULL POST-MERGE CHECKLIST

git status                          # 1. working tree clean
git diff --check                      # 2. zero leftover markers in uncommitted changes
git log --graph --oneline -5          # 3. merge commit has two parents
node -e "console.log(require('./config.js').port)"   # 4. file parses & value is sane
npm test                              # 5. behavior is actually correct

Step 4 is a smoke test that the resolved file at least parses as valid JavaScript; step 5 is the real proof. On a team, step 5 is exactly what CI runs on the merge result before anyone is allowed to deploy it.

Troubleshooting

Extension Ideas

• Configure a visual mergetool for big conflicts.
• Reduce conflicts by keeping branches short (see Branching).
• Catch issues earlier with CI in GitHub Actions.
• Enable merge.conflictStyle zdiff3 and re-run this lab to see the ancestor shown inside the markers.
• Try resolving with one-shot flags: git checkout --ours config.js or git checkout --theirs config.js when you know one side should win entirely.

Practice Challenges

Key Results

• Resolved a real conflict by reading the markers.
• Confirmed zero leftover markers with diff --check and a tree-wide marker grep.
• Validated correctness with tests, not just a clean status.
• Learned to abort and retry without panic.