Merge Conflicts
Resolving merge conflicts step by step — understanding conflict markers and resolution strategies.
What you'll learn
- How to read and understand conflict markers
- Step-by-step conflict resolution workflow
- Using merge tools and aborting conflicts
- Strategies to minimize conflicts in the first place
Concept
What Is a Merge Conflict?
A merge conflict occurs when two branches change the same lines of the same file and Git cannot determine which version to keep. Git pauses the merge and asks you to resolve the conflict manually.
git merge feature-branch
# Auto-merging login.js
# CONFLICT (content): Merge conflict in login.js
# Automatic merge failed; fix conflicts and then commit the result.
Conflicts are normal and nothing to fear — they happen every day in team development.
Conflict Markers
Git marks the conflicting section in the file:
function login(user) {
<<<<<<< HEAD
const token = generateToken(user);
return { token, user };
=======
const session = createSession(user);
return { session, user };
>>>>>>> feature-branch
}
<<<<<<< HEAD— your current branch's version (the one you are merging INTO)=======— the separator>>>>>>> feature-branch— the incoming branch's version (the one you are merging FROM)
The Resolution Workflow
- Identify the conflicts:
git statusshows files with conflicts as "both modified" - Open each conflicted file and find the
<<<<<<<markers - Edit the file to keep the correct version (or combine both)
- Remove the conflict markers (
<<<<<<<,=======,>>>>>>>) - Stage the resolved file:
git add <file> - Complete the merge:
git commit(orgit merge --continue)
Choosing the Resolution
You have several options for each conflict:
- Keep your version (HEAD) — delete the incoming code and markers
- Keep their version (incoming) — delete your code and markers
- Combine both — merge the logic from both versions
- Write something new — replace the entire conflicted section
For simple conflicts, you can use checkout to choose a side:
git checkout --ours conflicted-file.js # keep our version
git checkout --theirs conflicted-file.js # keep their version
git add conflicted-file.js
Using a Merge Tool
Configure and use a visual merge tool for complex conflicts:
git config --global merge.tool vscode
git mergetool
VS Code, IntelliJ, and other editors have excellent visual merge tools that show three panels: yours, theirs, and the result.
Aborting a Merge
If you are not ready to resolve conflicts:
git merge --abort
This cancels the merge and returns to the pre-merge state. You can always try again later.
Minimizing Conflicts
- Pull frequently — keep your branch up to date with main
- Communicate with your team — avoid editing the same files simultaneously
- Keep commits small and focused — smaller changes mean smaller conflicts
- Use feature branches — isolate work to reduce overlap
- Rebase before merging —
git pull --rebasekeeps your branch linear
Verifying the Resolution
After resolving, always verify your code works:
git add .
git commit # complete the merge
# Run your tests to make sure nothing broke
npm test
Never complete a merge without testing that the combined code actually works.
Example
# Simulate a conflict: two branches change the same line
git checkout -b feature-a
echo "Version A" > config.txt
git commit -am "feat: set config to version A"
git checkout main
echo "Version B" > config.txt
git commit -am "feat: set config to version B"
# Now merge — this will conflict
git merge feature-a
# CONFLICT (content): Merge conflict in config.txt
# See which files have conflicts
git status
# both modified: config.txt
# Open config.txt — it now contains:
# <<<<<<< HEAD
# Version B
# =======
# Version A
# >>>>>>> feature-a
# Edit the file to resolve — keep one or combine:
echo "Version A and B combined" > config.txt
# Stage the resolved file
git add config.txt
# Complete the merge
git commit -m "merge: resolve config.txt conflict"
# --- Alternative: keep one side entirely ---
git merge another-branch
git checkout --ours config.txt # keep our version
git add config.txt
git commit
# --- If overwhelmed, abort ---
git merge --abort
# --- Use a visual merge tool ---
git mergetool
# After resolving, verify everything works
npm test
Simulates a conflict by having two branches change the same file, shows the conflict markers, resolves by editing the file, stages and commits. Also shows the --ours/--theirs shortcuts, aborting, and using a merge tool. Always run tests after resolving conflicts.
Try it
- Code Diff
Compare conflicting versions side by side to decide the resolution.
- .gitignore Generator
Keep generated files out of Git to reduce merge conflicts.
Common mistakes
The mistake
Leaving conflict markers in the file and committing them
The fix
After resolving a conflict, search for <<<<<<<, =======, and >>>>>>> markers in your files before committing. These markers must all be removed. Run git diff --staged to verify the final state, and always run your tests after resolving.
The mistake
Panicking at a conflict and force-resetting, losing work
The fix
Conflicts are normal. If you are not ready, run git merge --abort to safely cancel and return to the pre-merge state. Never use git reset --hard to escape a conflict — it can lose uncommitted work. Take your time, resolve one file at a time, and test afterward.
Related Resources
Related Cheatsheets
- Git Cheatsheet
Conflict markers, resolution workflow, and merge --abort.
Practice Merge Conflicts
2 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.