17  Dealing with conflicts

🎯 Goal: By the end of this chapter, you’ll understand what merge conflicts are and how to resolve them.

Merge conflicts are an inevitable part of the collaboration process in Git. Knowing what to do when you encounter them will go a long way toward making your shared projects run smoothly.

17.1 What if you both edit the same file?

As we covered in the last chapter, before you make changes to your project you want to pull the most recent changes from the Github repo. When you run the git pull command, Git will automatically try to merge your local changes with the most-recent version of the file on the Github repo.

In an ideal world, Git is able to merge things without any issues. But sometimes, two people (or even just you on two different branches) will make different changes to the same lines of a file.

When you try to run git pull, Git gets confused and says:

“I don’t know which version you want to keep — you have to decide.”

This is called a merge conflict.

When merging, Git is trying to combine the changes from two versions of a file into one. Most of the time, if the changes are in different parts of the files, Git can handle it automatically.

But if two people made edits to the same part of a file (like the same sentence or section), Git doesn’t want to guess who’s right — so it stops and asks you to make the call.

Think of it like this:

  • You’re merging two Word documents together.
  • One version says “The sky is blue.”
  • The other version says “The sky is purple.”
  • Git says: “You can’t have both. Which one do you want?”

In Git world, this is a merge conflict, and Git needs your help to resolve it.

17.1.1 How will Git let me know there’s a conflict?

When Git encounters a merge conflict, two things will happen:

  1. In your Terminal, you’ll see a message like:

    Auto-merging filename.qmd CONFLICT (content): Merge conflict in analysis.qmd Automatic merge failed; fix conflicts and then commit the result.

  2. In the file with the conflict, Git will mark the conflicted lines like this:

    <<<<<<< HEAD This is your version. ======= This is your teammate’s version. >>>>>>> abc123

You’ll need to manually choose which version (or both!) to keep and then commit the right changes to Git. We’ll walk you through the process of resolving these conflicts in the section below.

17.2 How to resolve a merge conflict

Let’s say both you and a collaborator edited the same section of analysis.qmd and now Git is confused when you try to pull or merge.

Step 1: read the conflict message

When you run:

git pull

Git might respond with something like this:

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

This message tells you that the issue is in the file analysis.qmd. This is where you’ll need to resolve a merge conflict.

Step 2: Open the Conflicted File

  1. Open analysis.qmd in RStudio or your code editor.
  2. Find the conflict by looking for the text <<<<<<< HEAD. You can use the find feature (CMD+F) to search in RStudio if needed
  3. You’ll see something like: <<<<<<< HEAD The sky is blue. ======= The sky is purple. >>>>>>> origin/main

Here’s what this means:

  • <<<<<<< HEAD is your local version

  • ======= is the separator

  • >>>>>>> origin/main is the version you pulled from GitHub.

In other words:

  • Anything between <<<<<<< HEAD and the ======= separator are your current changes.
  • Anything between the ======= and >>>>>>> origin/main is what’s on the Github version.

Step 3: Choose What to Keep

Now it’s time to decide what version is correct.

You could:

  • Keep one
  • Combine them
  • Rewrite it entirely

Just make sure to delete the conflict markers (<<<<<<<, =======, >>>>>>>) when you’ve decided what you’d like to do.

Step 4: mark the conflict as resolved, commit and push

Once you’ve fixed the file, you need to tell Git it’s ready. We do this by saving our changes to the conflict file, then committing our changes and pushing the corrected file Github.

For our analysis.qmd conflict, for example, we’d do the following:

  1. Stage our resolved conflict file:

    git add analysis.qmd

  2. Commit our changes, noting the merge conflict in the commit message:

    git commit -m "Resolve merge conflict in analysis.qmd"

  3. Push the change to Github, so our team can see the resolution:

    git push

🎉 That’s it — you’ve handled a merge conflict like a pro.

17.3 Tips for Smooth Collaboration

  • Communicate! Decide who is editing what and when.
  • Always git pull before you start working.
  • Commit and push frequently — don’t wait until the end of the day.
  • Avoid working on the same file at the same time.

Next up

You’ll learn how to use feature branches to make collaborations smoother.