CHAPTER 04
Detecting and Analyzing Merge Conflicts
Updated: May 15, 2026
20 min read
# CHAPTER 4
Detecting and Analyzing Merge Conflicts
1. Introduction
You have typedgit merge, but instead of a success message, the terminal flashes red: CONFLICT (content). The merge has halted halfway through. Your repository is now in a special "Merging" state. Before you touch any code, you must stop, breathe, and analyze the situation. Trying to fix a conflict by guessing is a recipe for deleting production code. In this chapter, we will learn how to read Git's diagnostic output, locate the exact files causing the failure, and decipher the cryptic conflict markers (<<<<<<<) that Git injects directly into your source code.
2. Learning Objectives
By the end of this chapter, you will be able to:- Recognize the terminal output indicating a merge conflict.
-
Use
git statusto isolate conflicting files.
- Understand the "Merging" state of a repository.
-
Read and decipher Git conflict markers (
HEAD,=======,>>>>>>>).
- Determine the origin of incoming conflicting code.
3. Beginner Explanation
Imagine you hand in an essay to a harsh teacher.- The teacher doesn't just throw the essay in the trash.
- They take a giant red marker and draw a massive box around a bad paragraph.
- Inside the box, they write: "YOU WROTE THIS:" followed by your paragraph.
- Then they draw a line and write: "I WANT THIS INSTEAD:" followed by their perfect paragraph.
- They hand the paper back and say, "Cross one of them out, and bring it back to me."
Git is the teacher. The conflict markers are the red boxes. Git is asking you to cross out the bad code and keep the good code.
4. The Anatomy of a Conflict Alarm
When a conflict occurs, the terminal output is very specific:
text
Critical Rule: Do not type any other Git commands (like git pull or git checkout) right now. Your repository is frozen in a (main|MERGING) state. You must resolve this issue before Git will allow you to do anything else.
5. Isolating the Damage with git status
In a large project, you might merge a branch and get 15 different conflicting files. To find out exactly which files need your attention, type:
bash
Git will output a section called Unmerged paths:.
The files listed in red as both modified: are the ones containing conflicts.
Files listed in green were merged successfully and are safely waiting in the staging area.
6. Reading Conflict Markers
If you open a conflicted file (e.g.,index.html) in a basic text editor, you will see raw Git conflict markers injected directly into your HTML.
html
How to decipher the markers:
-
1.
<<<<<<< HEAD: Everything between this marker and the equal signs is the code that *currently exists on the branch you are standing on* (usuallymain).
-
2.
=======: The dividing wall.
-
3.
>>>>>>> feature-red-buttons: Everything between the dividing wall and this marker is the incoming code from the branch you are *trying to merge*.
7. Mini Project: Analyze Conflicting Code Changes
Let's return to our first conflict from Chapter 1 and analyze it.Step-by-Step Walkthrough:
-
1.
Navigate to the
conflict_testrepository from Chapter 1.
-
2.
If you resolved it, recreate it: ensure
mainhasColor: Greenandfeature-redhasColor: Redon the exact same line, and rungit merge feature-red.
-
3.
Run
git status. Observe the redboth modified: design.txtoutput.
-
4.
Open
design.txtin a raw text editor (like Notepad or Nano).
- 5. Analyze the block:
text
<<<<<<< HEAD
Color: Green
=======
Color: Red
>>>>>>> feature-red
`
-
6.
Understand the reality: Git is showing you that
main (HEAD) wants Green, and the incoming branch wants Red. You possess all the information required to make a decision. DO NOT edit the file yet!
8. Best Practices
-
Never Commit Markers: Conflict markers (
<<<<<<<) are not valid programming syntax. If you fail to delete them and accidentally commit the file, your HTML will be broken, your PHP will throw a Fatal Error, and your application will crash. Review your files carefully before committing the resolution.
9. Common Mistakes
-
The Accidental Accept: Developers sometimes see the conflict, get confused, and just delete everything between the markers, including the code. Or, they delete the markers but leave *both* sets of code, creating a duplicated, broken feature on the webpage. You must actively choose which logic to keep.
10. Exercises
-
1.
What command should you immediately run after a merge fails to determine which specific files are broken?
-
2.
Explain what the code between the
======= and >>>>>>> markers represents.
11. FAQs
Q: My IDE (like VS Code) shows fancy colors and buttons instead of the <<<<<<< symbols. Why?
A: Modern IDEs are smart enough to detect Git conflict markers. Instead of showing you the raw ugly text, they hide the text and overlay a beautiful graphical interface with buttons that say "Accept Current Change." We will explore this extensively in Chapter 6!
12. Summary
In Chapter 4, we learned how to approach a merge conflict calmly and analytically. We recognized that a halted merge places the repository into a suspended "Merging" state. By utilizing git status`, we accurately identified the damaged files. Most importantly, we learned to translate Git's raw, intimidating conflict markers into a clear, logical choice: "What is currently here (HEAD), versus what is trying to come in." Armed with this analytical framework, we are ready to execute the fix.