Lesson 5 of 8 in Git and collaboration

Resolving merge conflicts

Core10 minWritten for Git 2.28 or newer

A merge conflict happens when two branches changed the same lines in different ways and git cannot choose between them. Git stops, marks the disputed lines in the file, and waits for you to decide what the final text should be.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Branches and merging

The problem this solves

Git merges by comparing each branch with their shared base. If the branches touched different parts of a file, it combines them without help. If both rewrote the same line, any automatic choice would silently throw away someone's work.

So git stops and hands the decision to a person. Conflicts feel alarming the first time because the repository looks half-finished. It is not damaged. Git is in a paused state with a clear way out.

Calm is the main skill here. Once you know what the markers mean and which two commands finish or cancel the merge, conflicts become routine editing.

How it works

How a conflict arises and gets resolved
How a conflict arises and gets resolvedMain and feature both edit the same line, the merge stops with a conflict, you edit the file to the text you want, and add plus commit finish it.1 git merge1 same line2 conflict3 add, commitmain edits line 1feature edits line 1Merge stopsmarkers written in fileYou edit the filechoose the final textMerge commitafter add and commit
  • Runs code
  • Other
  • People and clients
  • Data

Main and feature both edit the same line, the merge stops with a conflict, you edit the file to the text you want, and add plus commit finish it.

  1. main edits line 1 to Merge stops: 1 git merge
  2. feature edits line 1 to Merge stops: 1 same line
  3. Merge stops to You edit the file: 2 conflict
  4. You edit the file to Merge commit: 3 add, commit

Two branches change the same line, so git cannot merge. It writes both versions into the file between markers and marks the file as unmerged. Every other file that merged cleanly is already staged.

The block between <<<<<<< HEAD and ======= is your side, the branch you were on when you ran the merge. The block between ======= and >>>>>>> feature is the incoming side. Your job is to edit the file to the text that should exist and delete all three marker lines.

You then run git add on the file to tell git it is resolved, and git commit to finish. If you would rather start over, git merge --abort puts everything back as it was before the merge.

Try it yourself

You will make a conflict on purpose in a throwaway repository, read it, abort once, then resolve it.

  1. 1
    Create two competing edits
    mkdir git-lab-4 && cd git-lab-4
    git init -b main
    git config user.name "Your Name"
    git config user.email "you@example.com"
    echo "hello" > greeting.txt
    git add greeting.txt && git commit -m "Add greeting"
    git switch -c feature
    echo "hello from feature" > greeting.txt
    git commit -am "Feature greeting"
    git switch main
    echo "hello from main" > greeting.txt
    git commit -am "Main greeting"
  2. 2
    Merge and hit the conflict
    git merge feature

    You should see

    Auto-merging greeting.txt
    CONFLICT (content): Merge conflict in greeting.txt
    Automatic merge failed; fix conflicts and then commit the result.
  3. 3
    Look at the state
    git status
    git diff --name-only --diff-filter=U
    cat greeting.txt

    You should see

    <<<<<<< HEAD
    hello from main
    =======
    hello from feature
    >>>>>>> feature

    The second command lists only unmerged files. The output shown is the content of greeting.txt. Git may print the markers slightly differently if you changed its conflict style setting.

  4. 4
    Back out, then try again
    git merge --abort
    cat greeting.txt
    git merge feature

    After the abort the file says hello from main again and the merge is gone. Running the merge a second time brings the conflict back.

  5. 5
    Resolve and finish
    echo "hello from main and feature" > greeting.txt
    git add greeting.txt
    git commit --no-edit
    git log --oneline --graph

    Overwriting the file removed all markers. In a real project you would edit the file in your editor, choosing or combining the sides, and run the tests before committing.

What breaks, and where to look

  • error: Committing is not possible because you have unmerged files.

    WHY IT HAPPENS
    You edited the conflicted file but did not tell git it is resolved with git add.
    CHECK FIRST
    Run git status and read the Unmerged paths section. Stage each resolved file with git add <file>, then commit.
  • A deployed page or config file contains lines starting with <<<<<<<, =======, or >>>>>>>.

    WHY IT HAPPENS
    Someone committed the file while the markers were still in it. Git does not check that markers are gone.
    CHECK FIRST
    Search before committing and in CI with git grep -n '<<<<<<<'. Fix the file and commit again.
  • The merge finished with no conflict, yet the application or pipeline fails afterwards.

    WHY IT HAPPENS
    Git merges text, not meaning. Two branches can change different lines that depend on each other, for example a function and a call to it.
    CHECK FIRST
    Run the tests or the build on the merged result before you push. A clean merge only means the text combined, not that the program works.

When not to use this

  • Frequent conflicts in the same files are a sign of long-lived branches or two people owning the same code. Merging small changes often removes most of them.
  • Generated files such as lock files are best regenerated with the tool that makes them rather than edited by hand. Resolve the source, then rebuild the file.

Check yourself

Why does git stop on a conflict?

Both branches changed the same lines in different ways, and choosing automatically would silently discard someone's work.

How do you finish a resolved conflict?

Edit the file to the final text, remove the marker lines, run git add on it, then git commit.

How do you cancel a merge that went wrong?

Run git merge --abort. It restores the state from before the merge started.

Lesson 35 of 92 in the DevOps path

Search

Search cheat sheets and projects