Git Tutorial – Part 6: Understanding and Resolving Merge Conflicts

Objective

In this tutorial, you will learn how to:

Understand what a merge conflict is.
Identify why merge conflicts occur.
Resolve merge conflicts using Visual Studio Code.
Complete the merge process.
Follow best practices to minimize merge conflicts.

Why Am I Seeing This Screen?

If you ran:

git merge feature/homepage

and Git opened a screen that looks like this:

Merge branch 'feature/homepage'
# Please enter a commit message to explain why this merge is necessary,
# especially if it merges an updated upstream into a topic branch.
# 
# Lines starting with '#' will be ignored, and an empty message aborts
# the commit.
~
~
~
.git/MERGE_MSG [unix]

this is usually not an error.

Git is opening its default text editor so you can confirm or edit the merge commit message.

What this means

The merge has reached the stage where Git wants to create a merge commit.
Git is waiting for you to save and close the editor.
The ~ lines are normal in Vim and simply mean empty lines.
.git/MERGE_MSG is the temporary file Git uses for the merge message.

What you should do right now

If you want to keep the default merge message:

Press Esc
Type:

:wq

Press Enter

This means:

w = write/save
q = quit

After that, Git will finish the merge.

If You Want to Use Visual Studio Code Instead of Vim

If you do not want Git to open Vim in the future, you can set Visual Studio Code as your Git editor:

git config --global core.editor "code --wait"

After this, Git will open VS Code when it needs you to enter a commit message.

What Is a Merge Conflict?

A merge conflict occurs when Git cannot automatically combine changes from two branches because the same part of a file has been modified differently.

Git pauses the merge process and asks you to resolve the conflict manually.

When Do Merge Conflicts Occur?

Common situations include:

Two developers modify the same line of code.
One developer deletes a file while another modifies it.
The same file is renamed differently in two branches.
Conflicting changes are made before pulling the latest updates from the remote repository.

Example Scenario

Assume two developers are working on the same file:

Developer A

Welcome to Git Tutorial

Changes it to:

Welcome to Git Tutorial Version 2

Developer B

Changes the same line to:

Welcome to Git Training Guide

Both developers commit their changes.

When Git attempts to merge the branches, it cannot determine which version should be kept.

Repository Before Merge

                 main
                  │
                  ●
                  │
        -------------------
        │                 │
        ▼                 ▼
 feature/login     feature/homepage

Both branches contain different changes.

Step 1: Create Two Branches

Start from the main branch.

Create the first branch:

git switch -c feature/login

Modify a file (for example, README.md) and commit the changes.

git add README.md
git commit -m "Update README from login branch"

Switch back to main.

git switch main

Create another branch.

git switch -c feature/homepage

Modify the same line in README.md.

Commit the changes.

git add README.md
git commit -m "Update README from homepage branch"

Step 2: Merge the First Branch

Switch to the main branch.

git switch main

Merge the first feature branch.

git merge feature/login

The merge should complete successfully.

If you see the .git/MERGE_MSG screen after running git merge feature/homepage, Git is usually waiting for you to confirm the merge commit message. In most cases, you should press Esc, type :wq, and press Enter.

Step 3: Merge the Second Branch

Now merge the second branch.

git merge feature/homepage

Git displays a conflict.

Example:

Auto-merging README.md

CONFLICT (content): Merge conflict in README.md

Automatic merge failed; fix conflicts and then commit the result.

Git has stopped the merge until the conflict is resolved.

Step 4: Check Repository Status

Run:

git status

Example output:

On branch main

You have unmerged paths.

Fix conflicts and run "git commit".

Git identifies the files that require attention.

Step 5: Open the Conflicted File

Open README.md in Visual Studio Code.

You will see conflict markers similar to:

<<<<<<< HEAD
Welcome to Git Tutorial Version 2
=======
Welcome to Git Training Guide
>>>>>>> feature/homepage

Understanding the Conflict Markers

<<<<<<< HEAD

Represents the current branch (main).

=======

Separates the two versions.

>>>>>>> feature/homepage

Represents the incoming changes from the branch being merged.

Step 6: Resolve the Conflict

Choose one of the following options:

Option 1: Keep the Current Change

Welcome to Git Tutorial Version 2

Option 2: Keep the Incoming Change

Welcome to Git Training Guide

Option 3: Combine Both Changes

Welcome to Git Tutorial Version 2

Welcome to Git Training Guide

Remove all conflict markers after deciding on the final content.

Save the file.

Step 7: Stage the Resolved File

After resolving the conflict, stage the file.

git add README.md

Git now recognizes that the conflict has been resolved.

Step 8: Complete the Merge

Complete the merge by creating a merge commit.

git commit -m "Resolve merge conflict in README"

Git records the successful merge.

Step 9: Verify the Merge

View the commit history.

git log --oneline --graph

Example output:

*   a45d2b1 Resolve merge conflict in README
|\
| * 9a76d21 Update README from homepage branch
| * 8d13ef4 Update README from login branch
|/
* 3b72ef5 Previous commit

The graph shows both branches merging into a single commit.

Visual Studio Code Merge Editor

Visual Studio Code provides a graphical Merge Editor.

When a conflict occurs, options such as the following appear above the conflicted section:

Accept Current Change
Accept Incoming Change
Accept Both Changes
Compare Changes

These options simplify conflict resolution without manually editing conflict markers.

Aborting a Merge

If you decide not to continue the merge:

git merge --abort

Git restores the repository to its state before the merge began.

Common Commands

Command	Description
`git merge <branch>`	Merge a branch into the current branch.
`git status`	Show files with merge conflicts.
`git add <file>`	Mark a conflict as resolved.
`git commit`	Complete the merge after resolving conflicts.
`git merge --abort`	Cancel the merge process.
`git log --oneline --graph`	Display branch and merge history.

Best Practices

Pull the latest changes before starting new work.
Commit changes frequently.
Keep feature branches short-lived.
Avoid making large, unrelated changes in a single branch.
Communicate with team members when working on the same files.
Review conflicts carefully before completing a merge.

Summary

In this chapter, you learned how to:

Understand why Git opens the merge commit message screen.
Recognize that this screen is usually normal and not an error.
Save and exit Vim using :wq.
Resolve merge conflicts manually.
Use Visual Studio Code’s Merge Editor.
Complete or abort a merge.
Follow best practices to reduce merge conflicts.

Understanding and Resolving Merge Conflicts in GIT