Lesson 5 of 8 in Git and collaboration
Resolving merge conflicts
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
- 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.
- main edits line 1 to Merge stops: 1 git merge
- feature edits line 1 to Merge stops: 1 same line
- Merge stops to You edit the file: 2 conflict
- 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.
- 1Create 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"
- 2Merge 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.
- 3Look 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. - 4Back out, then try again
git merge --abort cat greeting.txt git merge feature
After the abort the file says
hello from mainagain and the merge is gone. Running the merge a second time brings the conflict back. - 5Resolve 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 statusand read the Unmerged paths section. Stage each resolved file withgit 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.
Keep going
Lesson 35 of 92 in the DevOps path