git merge command helps a contributor add to a project from a branch. The concept is one of the core ideas of collaborative programming, allowing multiple people to work on their part of the code without any conflicts.
When multiple contributors work on the same part of a code or work with numerous branches, merge conflicts are bound to happen. The primary goal of
git merge is to resolve or warn about these conflicts automatically.
This guide explains what a merge conflict is and offers resolutions for when they do not sort out automatically. The article also provides helpful tips for preventing Git merge conflicts.
- Git installed and configured (On Windows, Mac and Ubuntu).
- A git merge conflict between a local and remote branch.
- Access to a terminal or command line
- Vim editor for the tutorial (To install Vim, follow one of our guides: How to Install Vim 8.2 on Ubuntu 18.04 or How to Install Vim 8.2 on CentOS 7)
What Is a Git Merge Conflict?
When working with version control systems such as Git, most merge conflicts resolve automatically. However, there are situations where
git merge is unable to resolve an issue.
Note: Check out our handy Git Commands Cheat Sheet, which features commonly used commands such as
Some examples of merge conflicts include:
- Changing the same lines of code in a file.
- Removal of files while changes happen in another place.
Since the problem happens locally and the rest of the project members are unaware of the issue, resolving the conflict is of high priority and requires an immediate fix.
Types Of Git Merge Conflicts
The general types of merge conflicts depend on when the issue appears. The conflicts happen either:
- Before merging, indicating there are local changes not up to date. The conflict error message appears before the merge starts to avoid issues.
- During the merge, indicating an overwrite issue. The error message appears and stops the merging process to avoid overwriting changes.
Note: Learn about the differences between git rebase and merge.
How To Resolve Merge Conflicts in Git
There are three ways to resolve a merge conflict in Git:
1. Accept the local version. To accept all changes on a file from the local version, run:
git checkout --ours <file name>
Alternatively, to accept the local version for all conflicting files, use:
git merge --strategy-option ours
2. Accept the remote version. To update the changes on a file from the remote branch, run:
git checkout --theirs <file name>
Accept the remote version for all conflicting files with:
git merge --strategy-option theirs
3. Review changes individually. The final option is to review each change separately. This option is also the best path to take, especially when working with multiple files and people. To make this job more manageable, use special tools to help review individual conflicts .
Ultimately, the choice of what parts of the code stay and which do not depends on the developer's decision for the current project.
Getting a Merge Conflict in Git
The merge conflict in Git happens when the command
git merge throws an error.
The error message prints the information about where the conflict is present. Check the file from the error message and look at the contents where the merge conflict happened:
Git automatically adds three indicators alongside the conflicting lines of code:
- <<<<<<< (seven "less than" characters) followed by HEAD, which is an alias for the current branch. The symbols indicate the beginning of the edits within this section.
- ======= (seven "equals sign" characters), which show the end of the revisions within the current branch and the beginning of the edits within a new one.
- >>>>>>> (seven "greater than" characters) followed by the branch where the attempted merge happened. The added symbols indicate the ending of the edits within the conflicting branch.
The added syntax helps search through the code to find the location of the merge conflict. However, a much more straightforward approach is to use a difference/merging tool to discover the issues and track the changes.
Note: Learn how to combine multiple commits by referring to our article How to Squash Commits in Git.
Setting Up a Default Diff Tool in Git
To set up the default diff tool for
1. Run the following line in your terminal:
git mergetool --tool-help
The output prints out all the supported diff tools for your current setup:
Different tools are available based on the editor of choice. For example:
- Emacs diff tools: Ediff or emerge
- Vim diff tools: vimdiff, vimdiff2 or vimdiff3
The further steps show an example of how to set up the vimdiff tool for Vim.
2. Change the
git config to set the default merge tool:
git config merge.tool <tool name>
For example, if using Vim, run:
git config merge.tool vimdiff
3. Set the diff tool to show the common ancestor for both files, which is the version before any edits:
git config merge.conflictstyle diff3
4. Set the option to not prompt before running:
git config mergetool.prompt false
The diff tool setup for Git is complete.
Using Mergetool to See the Differences
To use the
mergetool and see the differences, run:
The output displays a window with four views:
1. LOCAL represents the file version from the current branch.
2. BASE is how the file looked before any changes.
3. REMOTE shows how the file looks in the remote branch where the conflicting information is.
4. MERGED has the final merge file. This result represents what gets saved to the repository.
The primary navigation commands between these windows are:
- CTRL+WW to move between the windows.
- CTLR+WJ to jump to the MERGED window view.
- CTRL+WX to switch places of the windows.
For advanced navigation, information is available with the command
Updating and Resolving a Merge Conflict
Update the MERGED file to resolve a conflict. Some shortcuts for updating the MERGED version include:
- :diffg LOCAL updates the to the LOCAL version.
- :diffg BASE updates to the BASE version.
- :diffg REMOTE updates to the REMOTE version.
Note: Ensure the cursor is on the line where the conflicts are before running these commands.
Once the information is updated, save and quit with
Commit and Cleanup
The final step is to commit and clean up the extra files. Commit the updated version by running:
git commit -m "<your message>"
Note: If you made a mistake while committing, you could undo the last commit.
The diff tool creates extra files on the project for comparing versions. Clean them up with:
git clean -f
Tips On How to Prevent Merge Conflicts
Merge conflicts only happen when the computer is not able to resolve the problem automatically.
Here are some tips on how to prevent merge conflicts:
- Use a new file instead of an existing one whenever possible.
- Avoid adding changes at the end of the file.
- Push and pull changes as often as possible.
- Do not beautify code or organize imports on your own.
- Avoid the solo programmer mindset by keeping in mind the other people who are working on the same code.
Merge conflicts happen when working in Git or other version control programs from time to time. By following the instructions in this guide, you know how to handle merge conflicts and how to prevent them from happening.
For more Git resources, check out our article on What Is Git Upstream and How To Set Upstream Branch.