How to resolve a git merge conflict

Image by:

opensource.com

Git is the standard source code repository manager for open source projects and many closed source projects. This article shows new Git users how to do something slightly advanced but fundamental to its purpose: resolving a git-merge conflict.

What is a git merge?

All modern source-control systems have an essential feature: the ability for multiple developers to work on the same project, at the same time, without interfering with each other. Git implements this feature by allowing multiple developers to work on a branch locally, then push their code to a central place. Then, others can pull the code back to their local copy and continue their own work with their collaborators' changes in place.

When you want to bring the changes in a branch into your current branch, you use a git merge command. The merge takes all the changes in the other branch and applies them to the current branch.

What is a merge conflict?

In every situation where work can be parallelized, work will eventually overlap. Sometimes two developers will change the same line of code in two different ways; in such a case, Git can't tell which version is correct—that's something only a developer can decide.

If this happens, a developer will see the following error during a git merge:

Auto-merging [filename1]
CONFLICT (content): Merge conflict in [filename1]
Automatic merge failed; fix conflicts and then commit the result.

Resolving merge conflicts can take a minute or they can take days (if there are a lot of files that need to be fixed). It's recommended, and good coding practice, to sync your code multiple times a day by committing, pushing, pulling, and merging often.

How do you resolve a git merge conflict?

Git gives a clue to resolving conflicts in its error message. It says Merge conflict in [filename1], so you know there is a problem with that file. Then it says fix conflicts and then commit the result, so if you follow directions, edit the file, then commit it, everything should work fine. Let's see this in action.

Create a new Git repo, add a file, make a branch, make some conflicting edits, and see what it looks like.

Start with an empty directory and run git init:

$ ls -l
$ git init
Initialized empty Git repository in /home/bob/example/.git/
$

Now create a README file and commit the changes:

$ echo "This is a new README file" > README.md
$ cat README.md
This is a new README file
$ git add README.md
$ git commit -m "README file added"
1 file changed, 1 insertion(+)
create mode 100644 README.md
$ git status
On branch master
nothing to commit, working tree clean
$

Create a new branch:

$ git checkout -b "branch_to_create_merge_conflict"
Switched to a new branch 'branch_to_create_merge_conflict'

On the new branch:

$ git branch
* branch_to_create_merge_conflict
master

Make an edit:

This is a new README file

This is an edit on the branch

Now commit that edit:

$ vim README.md
$ git add README.md
$ git commit -m "Edits made to README on the branch"
[branch_to_create_merge_conflict 9c5e88a] Edits made to README on the branch
1 file changed, 2 insertions(+)

Return to the master branch, edit the README on line 3 with something different, and commit that.

Change to the master branch:

$ git checkout master
Switched to branch 'master'

Edit the README:

This is a new README file

This is an edit on the master branch

Commit the edit:

$ git add README.md
$ git commit -m "Edits made to README on the master branch"
[master 7ea2985] Edits made to README on the master branch
1 file changed, 2 insertions(+)

Merge the branch into master to see the error:

$ git branch
  branch_to_create_merge_conflict
* master
$ git merge branch_to_create_merge_conflict
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
Automatic merge failed; fix conflicts and then commit the result.

Now, go into the README file, as Git asks, to see what it looks like:

This is a new README file

<<<<<<< HEAD
This is an edit on the master branch
=======	
This is an edit on the branch
>>>>>>> branch_to_create_merge_conflict

As you can see, Git added some syntax including seven "less than" characters, <<<<<<< and seven "greater than" characters, >>>>>>>, separated by seven equal signs, =======. These can be searched using your editor to quickly find where edits need to be made.

That there are two sections within this block:

The "less than" characters denote the current branch's edits (in this case, "HEAD," which is another word for your current branch), and the equal signs denote the end of the first section.
The second section is where the edits are from the attempted merge; it starts with the equal signs and ends with the "greater than" signs.

As a developer, you decide what stays and what goes. Make your edits as necessary, then close the file:

This is a new README file

This is an edit on the branch

As you can see, this keeps the branch's edits. You can run git status to see further instructions:

$ vim README.md
$ git status
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 ..." to mark resolution)
  both modified: README.md
no changes added to commit (use "git add" and/or "git commit -a")

Notice that if you run into serious issues, you can abort the merge by running git merge --abort to abort the merge.

Follow the directions to add the file and then commit:

$ git add README.md
$ git status
On branch master
All conflicts fixed but you are still merging.
(use "git commit" to conclude merge)

Changes to be committed:
modified: README.md

$ git commit
[master 9937ca4] Merge branch 'branch_to_create_merge_conflict'

Key takeaways and further reading

Merge conflicts are going to happen on teams of any size, given enough time. It's important to be able to resolve them with a clear head. As a developer, I've been quite overwhelmed staring at a 10+ file merge-conflict problem. Understanding what you are looking at when you get a merge conflict goes a long way.

I didn't cover merge conflicts in the context of an integrated development environment. Knowing how to use the Git command-line tool, including fixing merge conflicts, is indispensable to understanding Git and being able to work on Git in any environment.

Git's website and documentation are good resources if you get stuck. You can find advanced information on Git merging, including merge-conflict resolution, in the advanced merging section of the Git Pro book.