Git: Case Study and Capstone - Understanding and Fixing Merge Conflicts

Sue Brownawell -

Note: this advice is for Team projects only - not for regular classes. If a merge conflict arises in a regular course, reach out to the sysadmin for help, since this is something that should never occur in a regular course.

Another note: if these directions are unclear or you encounter something different, contact the sysadmin for help and we can also revise the instructions.

Why Merge Conflicts Happen

Let's say you and a teammate have up-to-date repositories that match the remote repository. You both open and work on the same file, and commit your changes. Your teammate pushes their change before you do. When you push your changes, you get an error. For example, the message would include:

! [rejected]        master -> master (non-fast-forward)
error: failed to push some refs to <your remote repository>
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.

If you try pulling, the message may include:

error: Your local changes to the following files would be overwritten by merge:
        <a list of files affected>
Please commit your changes or stash them before you merge.
error: The following untracked working tree files would be overwritten by merge:
        <a list of files affected>
Please move or remove them before you merge.

This can happen if:

  • You run code in a notebook in a teammate's personal folder and commit that work. You should never commit anything in a teammate's personal folder.
  • You and your teammate are working on the same TeamArtifacts file without communicating well, working one at a time, and explicitly passing it off.

What a Merge Conflict Looks Like

When you run git status, you will see the conflicted notebooks listed under "Unmerged paths."

If you try opening the affected notebook you will get an File Load Error / unreadable notebook.

If you were to change the file extension to .txt instead of .ipynb, you would be able to open the notebook and see the problem. The merge conflict is marked with "<<<<<<< HEAD at the beginning, one teammates code following that, a separator "=======", then the other teammate's code, followed by >>>>>>> and a hash code.

Removing the markers and combining the changes can work to fix the conflict, but it is often a bear to fix if there are many conflicts, large conflicts, or you accidentally mess up the json so the notebook remains unreadable (which is very easy to do.) If you did manually edit the file, you would need to change the file extension back to .ipynb, stage the file for committing, make the commit, and push. We typically do not recommend manually editing the file unless the change is super simple, like the above example. See below for the recommended approach.

Fixing the Merge Conflict

Think it through

Do you want to have the file look like your teammate's or your own? You may want to look at the file on the remote git server in the browser to see what your teammate has done, and communicate with them about what you are both trying to do. If you want your teammate's code, you will use the --theirs flag when checking out the file; if you want yours, you will use the --ours flag.

Make the fix

  • Step 1:
# if you want your teammate's version:
git checkout --theirs <path to file>

# if you want your own version:
git checkout --ours <path to file>

Double check the file looks like you want it to

  • Step 2: Stage the file for the merge commit
    git add <path to file>

  • Step 3: Make the merge commit
    git commit -m "merging remote changes"

  • Step 4: Push the merge. Afterward, you may want to check that everything is up-to-date by running git status.

git push
git status
  • Step 5: If necessary, make the changes that you didn't accept (yours or your teammates), commit them and push again.

Need more information or help? Reach out to us at 📧 jcwdw@missouri.edu