Merge Conflicts and How to handle Them in Git

When many people work on the same code using Git, they may change the same files or lines without knowing it. This can confuse Git when it is trying to merge those changes, leading to a merge conflict. If you don’t understand how merge conflicts happen or how to fix them, it can slow down your work or even break your code.

In this article, we will learn what merge conflicts are, why they happen, the different types of conflicts, and how to solve them in simple steps. Understanding this will help you work better with a team and keep your project error-free.

What Are Merge Conflicts?

A merge conflict happens when Git tries to combine changes from two branches but finds overlapping edits it can't automatically sort out. This usually occurs when two branches edit the same lines in a file, or one branch deletes a file while another modifies it.

Why Do Merge Conflicts Occur?

Merge conflicts usually arise in the following scenarios:

1. Same line changed in two branches: If two people edit the same line in a file in different branches, Git can't choose which version is correct.

Example:

• Branch A: Welcome to our website!
• Branch B: Hello from our website!
  Git gets confused because both changed the same line.

2. One branch deletes a file, another edits it: If one branch deletes a file and another changes it, Git doesn't know whether to keep the file or remove it.

3. File renamed in one branch, edited in another: If a file is renamed in one branch and edited in another, Git doesn't know how to join those changes.

Scenario: Two People Editing the Same File

Imagine there is a file called notes.txt, and it has this content:

Hello, this is the project note.

Person A (on main branch) changes the file like this:

Hello, this is the **updated project note** by A.

Then commits the change.

Person B (on feature branch) changes the same line:

Hello, this is the **feature note** by B.

Then commits the change.

Now Person A tries to merge Person B’s branch (feature) into main

git merge feature

But Git gets confused! Both branches changed the same line differently. Git doesn’t know whose change to keep.

Git shows a merge conflict in notes.txt like this:

<<<<<<< HEAD
Hello, this is the **updated project note** by A.
=======
Hello, this is the **feature note** by B.
>>>>>>> feature

Types of Merge Conflicts

The below are different types of merge conflicts in git:

1. Content Conflicts (Edit–Edit)

This happens when two people change the same line in a file in different branches. Git doesn't know which version to keep.

2. Delete–Modify Conflicts

One branch deletes a file, and the other branch makes changes to it. Git gets confused should the file be kept or deleted?

3. Rename–Modify/Rename–Delete Conflicts

One branch renames a file, while the other branch edits or deletes it. Git can't track the file properly because the name is different.

4. Directory–File Conflicts (Structural Conflicts)

One branch turns a file into a folder, while the other branch still uses it as a file. Git doesn't know if it's a file or folder.

5. Submodule Conflicts

If both branches point to different versions of a submodule, Git doesn’t know which one to use.

6. Binary File Conflicts

If both branches make changes to a binary file (like an image or PDF), Git can’t compare them line-by-line. So it asks you to choose which version to keep.

7. File Mode Conflicts

One branch changes a file’s permissions (like making it executable), and the other branch doesn’t.
Git sees this as a conflict.

8. Index Conflicts

This happens inside Git’s staging area when things are changed in a way Git doesn’t know how to handle. Usually happens in more advanced Git operations like git rebase.

Creating a Merge Conflict

To show a simple example of how a merge conflict can happen, we can manually trigger a merge conflict from the following set of commands in any UNIX terminal / GIT bash :

Step 1: Create a new directory using the mkdir command, and cd into it.

Step 2: initialize it as a new Git repository using the git init command and create a new text file using the touch command.

Step 3: Open the text file and add some content in it, then add the text file to the repo and commit it.

Step 4: Now, its time to create a new branch to use it as the conflicting merge. Use git checkout to create and checkout the new branch.

Step 5: Now, overwrite some conflicting changes to the text file from this new branch.

Step 6: Add the changes to git and commit it from the new branch.

With this new branch: new_branch_for_merge_conflict we have created a commit that overrides the content of test_file.txt

Step 7: Again checkout the master branch, and this time append some text to the test_file.txt from the master branch.

Step 8: add these new changes to the staging area and commit them.

Step 9: Now for the last part, try merging the new branch to the master branch and you will encounter the second type of merge conflict.

So, now we have successfully triggered a merge conflict in Git.

Handling the Merge Conflict

As we have experienced from the proceeding example, Git will produce some descriptive output letting us know that a CONFLICT has occurred. We can gain further insight by running the git status command. This is what we will get after running the git status command:

On branch master
You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Unmerged paths:
  (use "git add <file>..." to mark resolution)
    both modified:   test_file.txt

no changes added to commit (use "git add" and/or "git commit -a")

On opening the test_file.txt we see some "conflict dividers". This is the content of our test_file.txt :

<<<<<<< HEAD
Adding some content to mess with it later
Append this text to initial commit
=======
Changing the contents of text file from new branch
>>>>>>> new_branch_for_merge_conflict

The ======= line is the "center" of the conflict. All the content between the center and the <<<<<<< HEAD line is content that exists in the current branch master which the HEAD ref is pointing to. Alternatively, all content between the center and >>>>>>> new_branch_for_merge_conflict is content that is present in our merging branch.

To resolve our merge conflict, we can manually remove the unnecessary part from any one of the branches, and only consider the content of the branch that is important for further use, along with removing the "conflict dividers" from our file. Once the conflict has been resolved we can use the git add command to move the new changes to the staging area, and then git commit to commit the changes.

How To Resolve Merge Conflicts?

Git prompts you to resolve conflicts manually when changes are made to the same part of the code in both branches. Here’s how to resolve conflicts:

Step 1: Identify the conflict files.

Git will display files that have merge conflicts. These files need manual resolution.

Step 2: Open the conflict files.

Use your preferred editor to open the conflicting files. Look for conflict markers

<<<<<<< HEAD
// Code from the current branch
=======
– Code from the merging branch
>>>>>>> branch-name

Step 3: Resolve the conflicts.

Remove the unnecessary changes, keeping the most relevant ones.

Step 4: Moving to the staging.

Once resolved, add the files to the staging area:

git add <file-name>

Step 5: Commit and Push the changes

After resolving conflicts commit the changes by using the below command.Including the message which gives information about changes made while resolving the conflicts.

git commit -m "message"

Push the changes made to the remote repository by using. Below command.

git push 

Common Git Merge Conflicts and their Fixes

While starting the merge: If there are changes in either the working directory or staging area, while merging, then Git will fail to start the merge. This happens because the pending changes could be overridden by the commits that are being merged. This is the error message provided by Git when this type of merge conflict happens :

error: Entry '<fileName>' not uptodate. Cannot merge. (Changes in working directory)
or,
error: Entry '<fileName>' would be overwritten by merge. Cannot merge. (Changes in staging area)

This type of conflict can be resolved either by doing git stash save "any_message_to_describe_what_is_saved" (Stashes away any changes in your staging area and working directory in a separate index) OR git checkout <file_name> (throws out your changes), and then the merge can be completed.

During the merge: This occurs because you have committed changes that are in conflict with someone else's committed changes. Git will do its best to merge the files and will leave things for you to resolve manually in the files it lists. This is the error message provided by Git when this type of merge conflict happens :

CONFLICT (content): Merge conflict in <fileName>
Automatic merge failed; fix conflicts and then commit the result.

This type of conflict can be resolved either by manually fixing all the merge conflict for each file OR using git reset ––hard (resets repository in order to back out of merge conflict situation).

Conclusion

In this article, we explored what a merge conflict is, the main reasons it happens such as editing the same line in different branches, deleting a file in one branch while editing it in another, or renaming files. We also looked at the different types of merge conflicts including edit-edit, delete-modify, rename conflicts, and more. To help understand it better, we saw a simple example showing how to create and resolve a merge conflict step-by-step using Git commands. We also learned how Git marks conflicting changes and how to fix them manually by choosing the correct content and removing conflict markers. Understanding merge conflicts and how to solve them is important for smooth collaboration in any project. It helps keep your work organized and your code error-free when working with others.