Merge conflicts are one of the most common pain points for Git users. This guide walks you through every step: detecting, understanding, and resolving conflicts — whether you prefer the CLI or a visual Git GUI like Gitoryx.
The Problem
You run git merge or git pull and Git stops dead: "CONFLICT (content): Merge conflict in src/app.js". Your terminal is frozen, your files are filled with <<<<<<< markers, and you have no idea which version to keep. Sound familiar?
Merge conflicts happen every day in collaborative development — any time two developers edit the same lines of code. Knowing how to resolve them quickly and safely is a core Git skill. Getting it wrong means corrupting shared code or losing work.
Common mistakes developers make with this:
Accepting all incoming changes without reading them
Forgetting to remove conflict markers (<<<<<<<, =======, >>>>>>>) before committing
Committing in a conflicted state
Aborting the merge when a simple resolution was possible
Gitoryx: Gitoryx shows conflicts visually — every conflicted file is highlighted with a warning badge, and a side-by-side diff editor lets you choose which version to keep (or combine both) in one click.
What is Resolve Merge Conflicts in Git?
A merge conflict occurs when Git cannot automatically reconcile changes from two branches because both modified the same lines of a file. Git pauses the merge and asks you to manually choose which changes to keep.
Step-by-Step Guide
1
Understand what triggered the conflict
A conflict usually happens after git merge, git rebase, or git pull. When Git encounters incompatible changes, it marks the conflicted files and pauses the operation.
bash
# Attempt a merge
git merge feature/login
# Git output when a conflict occurs:
# Auto-merging src/auth.js
# CONFLICT (content): Merge conflict in src/auth.js
# Automatic merge failed; fix conflicts and then commit the result.
Run git status immediately after a conflict to see which files need resolution.
2
Identify all conflicted files
Use git status to list every file in a conflicted state. Look for both modified in the output.
bash
git status
# Output:
# On branch main
# You have unmerged paths.
# (fix conflicts and run "git commit")
#
# Unmerged paths:
# (use "git add <file>..." to mark resolution)
# both modified: src/auth.js
3
Open the conflicted file and read the markers
Git inserts conflict markers directly into the file. The section between <<<<<<< and ======= is your current branch's version. The section between ======= and >>>>>>> is the incoming branch's version.
javascript
<<<<<<< HEAD
function login(user) {
return authenticate(user, { timeout: 5000 });
}
=======
function login(user, options = {}) {
return authenticate(user, options);
}
>>>>>>> feature/login
HEAD is always your current branch. The label after >>>>>>> is the branch being merged in.
4
Resolve the conflict
Edit the file to keep the version you want — or combine both. Delete all three conflict markers (<<<<<<<, =======, >>>>>>>) and leave only clean, valid code.
javascript
// Resolved version — combining both approaches:
function login(user, options = { timeout: 5000 }) {
return authenticate(user, options);
}
Never commit a file that still contains <<<<<<<, =======, or >>>>>>> markers. Your code will break.
See this workflow in Gitoryx. Conflicted files are highlighted with a warning badge in the file tree — no need to hunt through `git status` output.
A merge conflict occurs when two branches modify the same lines of the same file, or when one branch deletes a file that another branch modified. Git cannot determine which version to keep, so it pauses and asks you to decide.
How do I abort a merge and go back to my previous state?
Run git merge --abort at any point during an unfinished merge. This resets your working directory to the state it was in before the merge started.
What do the conflict markers mean?
<<<<<<< HEAD marks the start of your current branch's version. ======= separates the two versions. >>>>>>> branch-name marks the end of the incoming branch's version. Everything between these markers must be resolved manually.
Can I accept one side of a conflict automatically?
Yes. Use git checkout --ours filename to keep your version, or git checkout --theirs filename to keep the incoming version entirely. Only do this when you're certain which version is correct.
How do I prevent merge conflicts?
Pull frequently from the main branch to keep your feature branch up to date (git pull origin main). Communicate with your team about which files you're working on. Keep branches short-lived and focused on a single feature.
What is a merge tool in Git?
A merge tool is an external editor or built-in interface that displays conflicted files side by side, making it easier to compare and choose between versions. Configure one with git config --global merge.tool <toolname> or use a visual Git client like Gitoryx.
What happens if I commit with unresolved conflict markers?
Git will allow it (unless prevented by a hook), but your code will contain raw conflict marker text, breaking any file that is parsed — JavaScript, CSS, JSON, etc. Always run git diff --check before committing.
Does git rebase also cause merge conflicts?
Yes. Rebasing re-applies commits one at a time, so you may get a conflict at each commit. Resolve the conflict, run git add, then continue with git rebase --continue. Run git rebase --abort to cancel.
Everything in this tutorial is faster and clearer with a visual Git client. Gitoryx is free, runs natively on macOS and Windows, and built for developers who want to move fast without breaking things.
