Resolving conflicts

Last updated on 2023-10-11 | Edit this page

Overview

Questions

  • When might I encounter merge conflicts while maintaining/developing a lesson?
  • How can I resolve simple conflicts in the GitHub web interface?

Objectives

After following this section, participants will be ready to practice the following skills:

  • resolve merge conflicts using the GitHub web interface

What is a merge conflict?

A merge conflict occurs when Git is not able to automatically integrate (merge) the changes in a branch with the version of the relevant file(s) into another branch (usually the default or main branch) of the project.

Conflicts are seen when the target branch (usually main) has changed since the branch for the pull request was created. Often, Git is able to combine the two sets of changes without any trouble. But sometimes it gets stuck, and requires a human to intervene and decide how multiple changes should be combined, which change should take precedence, etc.

When these conflicts arise within a file, Git marks up the file contents to highlight them. The conflicts looks something like this:

<<<<<<< pr-branch
this is one version of the line. it exists in the version of this file in the pr-branch branch.
=======
this is another version of the same line. it exists in the version of this file in the main branch.
>>>>>>> main

Resolving a Merge Conflict

Before the PR can be merged, someone (usually the contributor who opened the pull request, or one of the repository Maintainers) needs to resolve each of these conflicts by:

  1. Figuring out which version (or combination of versions) of the lines should be kept in the file.
  2. Removing all other lines (including the <, =, and > symbols) to leave only that resolved version.

After that has been done, and no conflicts remain to be resolved, the branch can be updated, bringing it back in line with the changes in the target branch.

GitHub provides an interface to help you do this, with buttons for quick navigation between multiple conflicts, highlighting of the conflicting parts of the file, etc.

Larger Conflicts

Sometimes the conflicts between branches will be too large or too complex to be resolved within the GitHub web interface. In these cases, the conflicts will need to be resolved on the command line.

GitHub provides a guide to resolving conflicts on the command line, and other tools exist to help with merging and resolving conflicts.

Key Points

  • You may encounter merge conflicts in large pull requests and those that have been open for some time.
  • GitHub provides an interface to resolve simple conflicts in the GitHub web interface.