How to Resolve Merge Conflicts

How to use this guide

Resolving a merge conflict is a complex task that requires you to identify where the problem is coming from before being able to make a decision on which way to resolve it. If this is your first time encountering a merge conflict, I would recommend you read through What is a merge conflict or do some furthur research to get a better understanding. Otherwise if you already have some understanding of what a merge conflict is, you can follow the steps below to resolve it.

As you go through the steps, please click on the highlighted section links for more in-depth details and example outputs.

Step 1 : Identify the type of merge failure

• Read the very first Git merge error message in your terminal to determine whether it FAILED TO START or FAILED DURING THE MERGE, using Types of merge failures as a reference
• If FAILED TO START :
  • The resolution of this error message depends on what you want to do. You can discard your local changes and pull the ones in the repository or you can save your local changes into a stash and pull the version from the repository. It all depends on your preference.
  • There are 4 options provided in detail at this external web page Fixed: ‘Local changes to following files will be overwritten’ Git Error
• If FAILED DURING THE MERGE :
  • We have a hint from Git that there is a merge conflict, continue to Step 2 below to fix confict

Step 2 : Identify conflict files

• Use git status to list out all conflicted files:

  git status

Step 3 : Identify conflict lines in file

• Use either terminal command or Git command to display the difference in conflicted lines of code:
  • Using terminal command :

    $cat <fileName>

  • Using Git command :

    git diff

What is a merge conflict?

Version control systems like Git are all about managing contributions between multiple distributed authors (usually developers). Sometimes multiple developers may try to edit the same content. If Developer A tries to edit code that Developer B is editing a conflict may occur. To alleviate the occurrence of conflicts developers will work in separate isolated branches. The git merge command's primary responsibility is to combine separate branches and resolve any conflicting edits.

Understanding merge conflicts

Conflicts generally arise when two people have changed the same lines in a file, or if one developer deleted a file while another developer was modifying it. In these cases, Git cannot automatically determine what is correct. Conflicts only affect the developer conducting the merge, the rest of the team is unaware of the conflict. Git will mark the file as being conflicted and halt the merging process. It is then the developers' responsibility to resolve the conflict.

---

Types of merge failures

There are 2 ways in which git merge (or a git pull, which is a git fetch and then a git merge) can fail:

• Git fails to start the merge

  A merge will fail to start when Git sees there are changes in either the working directory or staging area of the current project. Git fails to start the merge because these pending changes could be written over by the commits that are being merged in. When this happens, it is not because of conflicts with other developer's, but conflicts with pending local changes. The local state will need to be stabilized using git stash, git checkout, git commit or git reset. You need to modify or stash the files it lists, and then try to do a git pull again. A merge failure on start will output the following error message:

  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)

  OR

  error: Your local changes to the following files would be overwritten by merge:
        <fileName>
  Please commit your changes or stash them before you merge

The 'merge failed to start" error message may be different than what's shown here depending on your Git version, but the message content would be more or less the same: telling you that you have local changes not staged or not commited, and that you need to take care of it or else it would be overwritten by the merge

• Git fails during the merge

  A failure DURING a merge indicates a conflict between the current local branch and the branch being merged. This indicates a conflict with another developer's commited changes. Git will do its best to merge the files but will leave things for you to resolve manually in the conflicted files. A mid-merge failure will output the following error message:

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

---

How to identify which file have conflicts

If your merge fail to even start, there will be no merge conflicts in file in the error message as shown in Types of merge failure: Git fails to start the merge.

If Git finds conflicts during the merge, it will list all files that have conflicts after the error message as shown in Types of merge failure: Git fails during the merge. You can also check on which files have merge conflicts by doing a git status, which will output as the following:

$ git status
On branch <current branch>
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:   <fileName>

---

How to find conflicts within the file

Using terminal command

You can examine the conflicted file and see what lines/area in the file that caused the conflicts by using the cat command in the terminal:

$ cat <fileName>

then the output would show as the following:

<<<<<< HEAD
this is where it will show content or lines of code 
that already exists in the current branch before merge intiated
=======
this is where it will show conetent or lines of code
that you committed in the new branch that you are trying to merge into
the current branch
>>>>>>> new-branch-to-merge

Think of these new lines as "conflict dividers". The=======line is the "center" divider of the conflict. All the content between the <<<<<<< HEAD line and the "center" is content that exists in the current branch which the HEAD ref is pointing to. Alternatively all content between the center and >>>>>>> new_branch_to_merge is content that is present in your merging branch.

Using Git command

Alternatively, you can use git diff to see the difference between this branch and the one we are merging into:

git diff

Example output:

++<<<<<<< HEAD
 +Some  a
 +Some b
 +Some conflict c 
 +Some conflict d
 +Some e
++=======
+ Some conflict 1
+ Some b
+ Some conflict c
+ Some conflict 2
 -Some f
++Some f
++>>>>>>> main

---

How to resolve merge conflicts using the command line

The most direct way to resolve a merge conflict is to edit the conflicted file. Open the conflicted file in your favorite editor or IDE and manually edit the conflicted lines. This may mean that you need to make a decision on discarding either your changes or someone else's or doing a mix of the two. You will also need to delete the conflict dividers <<<<<<<, =======, and >>>>>>> in the file.

Once file has been edited, make sure you save the changes, then use git status to check if the conflict messages is still showing (example conflict message after git status); otherwise if the conflict is resolved it should show normal output for git status, listing the modified files to be staged:

On branch <current branch>
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   <fileName>

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

After conflict is confirmed resolved, use git add to stage the new merged content:

git add <fileName>

It's best practice to always use git status again after git add to check if files were staged correctly, same goes for commits before push.

To finalize the merge, create a new commit by executing:

git commit -m "merged and resolved the conflict in yourFileName"