merge conflicts

A merge conflict happens when Git cannot automatically reconcile two sets of changes. It occurs when two branches modify the same lines of the same file in different ways, or when one branch deletes a file that the other branch has edited. Because Git cannot know which version is correct, it pauses the merge and hands the decision to you.

This page explains why conflicts happen, how to reproduce one, how to read the markers Git inserts into your files, and the different ways to resolve, abort, or even prevent a conflict. The git merge command is what combines two branches and is where most conflicts surface.

Git handles merging better than most version control systems and integrates changes automatically whenever the two sides touch different parts of a file. A conflict is therefore not an error in your workflow — it is Git asking for a human decision. When it cannot decide, it marks the file as conflicted and stops the merge so nothing is lost.

When do conflicts happen?

Not every merge produces a conflict. Knowing when one is likely helps you avoid surprises:

• Same lines edited on both sides — the classic case. Two branches change the same line of example.txt differently.
• A file edited on one branch, deleted on the other — Git cannot decide whether to keep the edits or honor the deletion.
• Whitespace, line-ending, or encoding mismatches — changes that look identical can still conflict if the bytes differ.

When the two branches touch different lines or different files, Git merges them automatically with no conflict at all.

Common merge interruptions

Git can stop a merge at two distinct points, and the two cases need different fixes. It helps to know which one you are looking at.

Merge failure on start

Git refuses to begin a merge when uncommitted changes in your working directory or staging area would be overwritten by the incoming commits. This is not a content conflict — it is Git protecting work you have not committed yet. To take control of your local state, use git stash (shelve the changes), git commit (save them), git checkout, or git reset (discard them), then run the merge again. The message looks like this:

error: Your local changes to the following files would be overwritten by merge:
	example.txt
Please commit your changes or stash them before you merge.
Aborting

Failure during merge

A failure during the merge means Git started combining the branches but hit a real content conflict between your current branch and the branch you are merging in. The merge is left half-done so you can resolve it. The message looks like this:

CONFLICT (content): Merge conflict in example.txt
Automatic merge failed; fix conflicts and then commit the result.

Creating a merge conflict

You can reproduce a conflict in a throwaway repository so you can practice resolving one safely. Start by creating a repository with a single committed file:

mkdir test-dir
cd test-dir
git init .
echo "some content" > example.txt
git add example.txt
git commit -m "initial commit"
[master (root-commit) a45c22d] initial commit
1 file changed, 1 insertion(+)
create mode 100644 example.txt

This creates a directory named test-dir, initializes a repository, and commits example.txt with the line some content. We now have one branch (master) and one file. Next, create a second branch and change the same line — this is what makes the conflict possible:

git checkout -b branch_to_merge
echo "completely different content to merge later" > example.txt
git commit -m "edit the content of example.txt to make a conflict"
[branch_to_merge 4221135] edit the content of example.txt to make a conflict
1 file changed, 1 insertion(+), 1 deletion(-)

git checkout -b branch_to_merge creates the branch and switches to it. We overwrite example.txt and commit the change, so this branch now has a different version of that line. Switch back to master and change the same file a different way:

git checkout master
Switched to branch 'master'
echo "content to add" >> example.txt
git commit -m "added content to example.txt"
[master 11ab34b] added content to example.txt
1 file changed, 1 insertion(+)

Now both branches have their own commit touching example.txt. Run the merge, and Git reports the conflict it cannot resolve on its own:

git merge branch_to_merge
Auto-merging example.txt
CONFLICT (content): Merge conflict in example.txt
Automatic merge failed; fix conflicts and then commit the result.

Identifying merge conflicts

Besides the message printed by the merge, git status tells you exactly which files are conflicted by listing them under Unmerged paths:

git status
On branch master
You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Unmerged paths:
  (use "git add <file>..." to mark resolution)
	both modified:   example.txt

both modified means the file changed on both sides. Open or cat the file to see the conflict markers Git inserted:

cat example.txt
<<<<<<< HEAD
some content
content to add
=======
completely different content to merge later
>>>>>>> branch_to_merge

Read the three markers like this:

• <<<<<<< HEAD — start of the conflict. Everything below it down to ======= is your current branch (master, where HEAD points).
• ======= — the dividing line between the two versions.
• >>>>>>> branch_to_merge — end of the conflict. The lines between ======= and this marker come from the branch you are merging in.

To throw the whole merge away and return to the exact state before you started, run git merge --abort. You can read more about the markers on the git merge page.

Resolving merge conflicts

Resolving by hand

Open the conflicted file in your editor, decide what the final content should be, and delete all three markers (<<<<<<<, =======, >>>>>>>). You may keep one side, the other, or a hand-merged combination of both. For example, keeping both pieces of content gives:

some content
content to add
completely different content to merge later

Once the markers are gone and the content is correct, stage the file with git add and commit to finish the merge:

git add example.txt
git commit -m "resolve merge conflict in example.txt"

Running git commit after a conflict creates a merge commit that ties both branch histories together.

Resolving by picking one side

When you simply want to keep one branch's version of a file wholesale, you do not have to edit by hand. Check out the side you want, then stage and commit:

git checkout --ours example.txt    # keep the version from the current branch (master)
git checkout --theirs example.txt  # keep the version from the incoming branch
git add example.txt

--ours keeps your current branch's content; --theirs keeps the incoming branch's content.

Resolving with a visual tool

For larger conflicts, git mergetool opens a configured side-by-side diff tool so you can resolve conflicts interactively instead of editing markers manually. Run git mergetool to walk through every conflicted file, or git mergetool example.txt for a specific one.

Aborting a merge

If you decide the merge was a mistake, or you would rather start over with a clean working tree, abort it:

git merge --abort

This restores your branch and working directory to the exact state they were in before you ran git merge — no markers, no half-merged files. Use it whenever the conflict is more than you want to deal with right now.

Preventing merge conflicts

Conflicts are normal, but you can reduce how often and how badly they hit you:

• Merge or rebase from the main branch often so your branch never drifts far from it.
• Keep commits small and focused, and avoid sweeping reformatting in the same change as logic edits.
• Communicate so two people are not rewriting the same file at the same time.
• Preview the overlap with git diff before merging to see which lines might collide.

Commands cheat sheet

These are the commands you reach for most often when handling conflicts:

Practice