Resolving Merge Conflicts
Module: Git Integration | Lesson: 4 of 4 | Time: ~10 minutes
What You Will Learn
- What merge conflicts are and why they happen
- How Claude detects and explains conflicts
- How to resolve conflicts with Claude's guidance
Prerequisites
- Completed Pull Requests and Reviews
What Is a Merge Conflict?
In the previous lessons, you learned how to create branches, make commits, and merge pull requests. Most of the time, merging "just works" — Git combines changes from two branches automatically. But sometimes Git gets stuck.
A merge conflict happens when two branches change the same lines in the same file, and Git cannot figure out which version to keep. It is like two people editing the same sentence in a shared document at the same time — someone has to decide which edit wins.
Here is a simple example:
- On the main branch, line 5 of
style.csssays:color: blue; - On your feature branch, you changed line 5 to:
color: red; - Meanwhile, someone else changed line 5 on main to:
color: green;
When you try to merge, Git sees two different changes to the same line and does not know which one you want. It stops and asks you to decide.
Merge conflicts are not a sign that something went wrong. They are a normal part of working with Git, especially when multiple people are editing the same files. The key is knowing how to resolve them — and Claude makes this much easier.
What a Merge Conflict Looks Like
When a conflict occurs, Git marks the conflicting sections in the file with special markers:
<<<<<<< HEAD
color: green;
=======
color: red;
>>>>>>> feature-branch
Here is what each part means:
| Marker | Meaning |
|---|---|
<<<<<<< HEAD | Start of the version from the branch you are merging into (usually main) |
======= | Divider between the two versions |
>>>>>>> feature-branch | End of the version from the branch you are merging from |
Everything between <<<<<<< HEAD and ======= is what the main branch has. Everything between ======= and >>>>>>> feature-branch is what your branch has.
To resolve the conflict, you need to:
- Choose one version, the other, or a combination of both.
- Remove the conflict markers (
<<<<<<<,=======,>>>>>>>). - Stage and commit the resolved file.
How Claude Helps Resolve Conflicts
This is where Claude Code really shines. Instead of manually editing conflict markers (which is confusing and error-prone), you can ask Claude to help.
Detecting Conflicts
When you try to merge and there is a conflict, Claude will tell you:
You: Merge the feature-branch into main
Claude: The merge has conflicts in the following files:
- style.css (1 conflict)
- index.html (2 conflicts)
Would you like me to help resolve them?
Understanding the Conflict
Ask Claude to explain what happened:
You: Explain the conflict in style.css
Claude: In style.css, line 5 has a conflict:
- The main branch changed the text color to green
- Your feature branch changed it to red
- Both changes happened after the branches diverged
The main branch version: color: green;
Your branch version: color: red;
Which would you like to keep?
Resolving the Conflict
You have several options:
Keep your version:
You: Keep my version (the red color)
Keep the other version:
You: Keep the main branch version (the green color)
Combine both:
You: Actually, use color: purple — a mix of both
Let Claude decide:
You: Resolve this conflict in whatever way makes the most sense
Claude will edit the file, remove the conflict markers, and leave you with clean code.
Finishing the Merge
After all conflicts are resolved:
You: Are all conflicts resolved? If so, finish the merge.
Claude will stage the resolved files and create a merge commit.
Resolving Multiple Conflicts at Once
If a merge has several conflicts across multiple files, you can ask Claude to handle them all:
You: Resolve all merge conflicts, keeping my branch's changes where
there is a disagreement about functionality, but keeping main's
changes for styling
Claude will go through each conflict, apply your instructions, and resolve them one by one.
A Complete Conflict Resolution Example
Here is a realistic walkthrough:
You: Merge the add-dark-mode branch into main
Claude: The merge resulted in conflicts in 2 files:
1. style.css — 1 conflict (both branches changed the body background)
2. app.js — 1 conflict (both branches modified the init function)
Would you like me to show the details?
You: Yes, show me both conflicts
Claude: **style.css, line 3:**
- main has: background-color: #ffffff;
- add-dark-mode has: background-color: #1a1a1a;
**app.js, line 12:**
- main has: console.log("App started");
- add-dark-mode has: console.log("App started in dark mode");
applyTheme('dark');
How would you like to resolve these?
You: For style.css, keep the dark mode version. For app.js, keep both
the log message from dark mode AND the applyTheme call.
Claude: Done. I've resolved both conflicts:
- style.css now uses background-color: #1a1a1a
- app.js now logs "App started in dark mode" and calls applyTheme('dark')
All conflicts are resolved. Shall I commit the merge?
You: Yes, commit it
Claude: Merge commit created: "Merge branch 'add-dark-mode' into main"
Preventing Merge Conflicts
While conflicts cannot be avoided entirely, you can minimize them:
Tip 1: Pull Before You Branch
Always get the latest version of main before creating a new branch:
You: Pull the latest changes from main, then create a new branch called my-feature
Tip 2: Keep Branches Short-Lived
The longer a branch lives, the more likely it is that main will change underneath you. Try to make small, focused branches that you merge within a day or two.
Tip 3: Communicate With Your Team
If you know a teammate is editing the same file, coordinate. "I'm about to rework the header — hold off on header changes until I merge."
Tip 4: Pull Main Into Your Branch Regularly
If your branch lives for more than a day, periodically bring in the latest changes from main:
You: Pull the latest main branch into my current branch
This lets you resolve small conflicts incrementally instead of facing one big conflict at merge time.
Tip 5: Avoid Formatting-Only Changes
Reformatting an entire file (changing indentation, reordering imports, etc.) creates huge diffs that almost guarantee conflicts with anyone else editing that file. Make formatting changes in separate, dedicated commits.
Try It Yourself
Let us create a conflict on purpose so you can practice resolving it:
-
Create a new project (or use your existing practice project):
mkdir conflict-practice
cd conflict-practice
claude -
Set up the project:
Initialize a Git repo, create a file called greeting.txt with the content
"Hello, World!", and commit it -
Create a branch and make a change:
Create a branch called change-greeting, then change greeting.txt to say
"Hello, Universe!" and commit it -
Switch back to main and make a conflicting change:
Switch to the main branch, change greeting.txt to say "Hello, Earth!"
and commit it -
Try to merge — this will create a conflict:
Merge the change-greeting branch into main -
Resolve the conflict with Claude's help:
Show me the conflict and help me resolve it. I want it to say
"Hello, Universe and Earth!" -
Finish the merge:
Commit the resolved merge -
Verify everything is clean:
Show me the git log and the contents of greeting.txt
What You Learned
- A merge conflict happens when two branches change the same lines in the same file.
- Git marks conflicts with
<<<<<<<,=======, and>>>>>>>markers. - Claude can detect, explain, and resolve conflicts for you — just describe which version you want to keep.
- You can resolve conflicts by keeping one version, combining both, or writing something new.
- Prevention tips: pull before branching, keep branches short-lived, communicate with teammates, and pull main regularly.
How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.