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, Windows, and Linux, and built for developers who want to move fast without breaking things.
