Himanshu SharmaSoftware engineer
Let’s talk

Git and GitHub · Lesson 12 of 30

Resolving merge conflicts step by step

Learn why merge conflicts happen, read the conflict markers, resolve a conflict by hand, finish the merge, or abort safely, with a calm checklist.

14 minBranches and mergingUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonRecognise a merge conflict, read the markers, edit the file to the result you want, and complete or abort the merge.

What you can do after this lesson

You will meet a merge conflict without panic, read what Git is telling you, and finish the merge with the text you decide on. Conflicts look dramatic, but they are routine in team work. They are simply Git saying "two people edited this same spot, and I will not guess".

When conflicts happen

If two branches change different files, or different parts of one file, Git combines them automatically. A conflict arises only when both branches modified the same lines in different ways, or one deleted a file the other changed. Git cannot know whether the price should be 2.00 or 2.50, so it stops and asks.

Here is the fictional setup, a cafe menu. Both branches start from this file:

text
Soup of the day
Bread basket
Tea

On a prices branch someone changed the last line to Tea (2.00). Meanwhile on main someone else changed it to Tea (2.50). Now we merge:

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

The merge has paused halfway. Nothing is broken. git status -s shows the file with two letters:

text
UU menu.txt

UU means unmerged on both sides.

Reading the markers

Open the file in your editor. Git has written both versions into it:

text
Soup of the day
Bread basket
<<<<<<< HEAD
Tea (2.50)
=======
Tea (2.00)
>>>>>>> prices
  • Everything between <<<<<<< HEAD and ======= is your side, the branch you are on (main).
  • Everything between ======= and >>>>>>> prices is the incoming side, from the branch you are merging.
  • Lines outside the markers merged cleanly.

Many editors, including Visual Studio Code, add buttons such as "accept current", "accept incoming" and "accept both". Those just edit the same text.

Resolving

You decide the final content. You might keep one side, keep the other, or combine them into something new. The one rule is that the markers must go. Suppose you and the team agree on 2.50:

text
Soup of the day
Bread basket
Tea (2.50)

Save the file, then tell Git it is resolved by staging it, and complete the merge:

bash
git add menu.txt
git commit --no-edit
text
[main dc60984] Merge branch 'prices'

--no-edit keeps Git's default message; without it your editor opens with that message ready. The hash will differ in your repository. The history now records the merge with both parents:

bash
git log --oneline --graph
text
*   dc60984 Merge branch 'prices'
|\  
| * 9502e6e Price the tea at 2.00
* | e8fa632 Price the tea at 2.50
|/  
* 0e4fda5 Add menu

Finding all conflicted files

With many files, list the ones still unresolved:

bash
git diff --name-only --diff-filter=U
text
menu.txt

git status also lists them under "Unmerged paths". Work through them one at a time. A fast safety check before committing is to search your files for leftover markers; a committed <<<<<<< line is a classic embarrassment. In a real project you can search for <<<<<<< across the folder.

Bailing out

If the situation is confusing, you do not have to continue:

bash
git merge --abort
git status -s

The second command prints nothing: the working tree is clean and the merge never happened. You can then try again, perhaps after talking to the person who made the other change. That conversation is often the real fix, because only a human knows which price is right. If you want to compare the two versions of text outside Git, the text diff tool shows differences between any two pieces of text.

Different conflict shapes

The example above is the common "both modified" type. When two branches each add a file with the same name, Git reports add/add and puts markers in it just the same, as in this case from a verified run: CONFLICT (add/add): Merge conflict in fees.txt. Other types include a file modified on one side and deleted on the other. The status output names the type, and the resolution is the same idea: decide, edit or delete, git add, commit.

Reducing conflicts

You cannot remove conflicts, but you can make them smaller and rarer:

  • Keep branches short-lived and merge often.
  • Pull the latest main into your branch regularly, so you meet differences while they are small.
  • Make focused commits and avoid reformatting whole files while others are editing them.
  • Talk to teammates before large edits to the same file.

Common mistakes

  • Leaving the markers in the file. Search for <<<<<<< before staging.
  • Choosing a side without reading it. Check whether both sides contain something you need.
  • Committing without git add. Git refuses while files are unmerged, and tells you which.
  • Panicking and deleting the repository. git merge --abort is the exit.
  • Resolving silently on behalf of someone else. If you are unsure of their intent, ask.

Exercise

  1. Create a file greeting.txt with the line Hello, commit it, and create branches formal and casual from there.
  2. On formal change the line to Good day; on casual change it to Hi there. Commit each.
  3. Merge casual into formal. Resolve the conflict by keeping Good day, hi there.
  4. Check the log graph, and then repeat the merge but abort it instead.
Show one possible answer
bash
echo Hello > greeting.txt && git add . && git commit -m "Add greeting"
git switch -c formal && echo "Good day" > greeting.txt && git commit -am "Formal"
git switch -c casual main && echo "Hi there" > greeting.txt && git commit -am "Casual"
git switch formal
git merge casual
echo "Good day, hi there" > greeting.txt
git add greeting.txt
git commit --no-edit
git log --oneline --graph

To practise aborting, reset with git reset --hard HEAD~1, merge again, then run git merge --abort.

Next: Rebasing: replaying a branch onto a new base, and when not to.

Key points

  • A conflict happens when two branches change the same lines differently and Git cannot choose for you.
  • Git marks the file with <<<<<<<, ======= and >>>>>>> lines; your job is to produce the final text and delete the markers.
  • After editing, run git add on the file and then git commit (or the continue command) to finish.
  • git merge --abort returns you to the state before the merge, so you can always start again.
  • A conflict is not an error; it is Git asking a human to decide.

Check yourself

1. What causes a merge conflict?
2. In a conflicted file, what appears between <<<<<<< HEAD and =======?
3. You fixed the text in a conflicted file. What do you do next?
4. You are halfway through a messy conflict and want to start over. Which command helps?

Free tools for this lesson