A Merge Conflict is a pause in the integration process that occurs when Git detects two contradictory modifications in the same file and requires your manual intervention.
You are trying to integrate a branch with git merge (or pulling a colleague’s code with git pull). Everything seems fine until the terminal gives you the message:
CONFLICT (content): Merge conflict in index.html
Automatic merge failed; fix conflicts and then commit the result.
Technically, a conflict is not an “error”; it’s Git being conservative. It has found two different versions for the same line of code and, since it can’t guess which one is correct, it pauses the operation and passes the ball to you.
In this article, we will understand the anatomy of a conflict, how to interpret the markers Git injects into your files, and how to resolve them visually by leveraging the VS Code interface.
Why does a conflict occur?
A merge conflict occurs when there are two different changes to the same element.
For example:
- Two people (or you in two different branches) have modified the same line of the same file differently.
- One person has modified a file and the other has deleted it.
In these cases, Git cannot decide whether change A or B is the correct one. It cannot resolve the merge automatically. So it pauses the merge and leaves the file in a special state.
Resolving conflicts in VS Code
It’s possible to fix a conflict by manually deleting the lines with the <<<< and ==== symbols. But basically doing it without a GUI is hell.
Visual Studio Code automatically detects this format and offers us a visual interface to fix it that is much easier.
When you open the conflicted file in VS Code, you will see that it highlights the blocks in colors and offers you some buttons above the conflict. The options are:
If you click here, VS Code keeps your version (the one from HEAD) and deletes the version coming from the other branch.
That is, “My code is the good one, the other person’s is wrong”.
If you click here, VS Code keeps the version from the other branch and deletes yours.
That is, “What comes from the feature branch is more correct, overwrite mine”.
It keeps both blocks of code, one below the other, and only deletes the Git markers.
That is, “I need both lines”.
You will usually have to manually reorder the code after this for it to make sense.
Closing the conflict
You’ve used the VS Code buttons, the file looks fine now. There are no more conflicts. But if you look at your terminal, Git still says it’s in a “MERGING” state.
Git doesn’t know you’ve finished editing the file in VS Code; you have to tell it. The complete process is:
You resolve the conflict in the editor.
Save the file (Ctrl+S).
Go to the terminal and run:
git add filename
By adding it to the Stage, you tell Git: “This file is already fixed, mark it as resolved”
Once all conflicted files are fixed, finalize the merge with:
git commit
If you don’t provide a message with the -m parameter, Git will generate an automatic one like “Merge branch ‘feature’ into main”.
The panic button: git merge --abort
Sometimes, you start resolving conflicts, get confused, delete something you shouldn’t have, and the code stops making sense. You panic. You want to get out of there.
If you want to cancel the merge and leave everything exactly as it was before typing git merge, run:
git merge --abort
The repository will return to the clean state it was in before the merge attempt.
The best conflict is the one that never happens
Merge Conflicts are the most frequent problem in collaborative work. Depending on the size of the changes, a conflict can be a five-second task or a monumental mess.
The way to resolve conflicts is to NOT GENERATE THEM. For that, the best way is:
- Team communication. Agree on what each person works on.
- Having a clean architecture that facilitates collaborative work.
