How to Resolve Merge Conflicts

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)

• 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 main
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

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.

---

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>

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

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