Resolving Merge Conflicts

Merge conflicts happen when Git cannot automatically combine changes from different branches.
They are a normal part of collaboration — especially when several students work in the same files.

This guide explains:

• How to resolve simple merge conflicts directly on GitHub
• When you must resolve conflicts locally
• Best practices to avoid merge conflicts in the future

---

🧠 Why Merge Conflicts Happen

Common causes include:

• Two people editing the same lines in a file
• A file being deleted or renamed in one branch but modified in another
• Long-running branches that fall behind develop or main

Learning to resolve conflicts is an essential skill for developers.

---

🟦 Resolving Simple Merge Conflicts on GitHub

GitHub allows you to resolve competing line changes (simple conflicts) using its built-in conflict editor.

You can only use this method if:

• Both branches changed the same specific lines,
• And GitHub detects that the conflict can be manually corrected in the browser.

For more complex conflicts, you must resolve them locally.

Official GitHub docs:
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github

---

🧰 Steps: Resolving Conflicts on GitHub

1. In your repository, click Pull requests.
   

2. Select the pull request with the merge conflict.

3. Scroll to the bottom and click Resolve conflicts.
   

   Note: If the button is disabled, the conflict is too complex for the GitHub editor.
   You must resolve it on your computer using Git.

4. Inside the conflict editor, choose how you want to merge the conflicting changes:

   • Keep your branch’s changes
   • Keep the other branch’s changes
   • Combine and rewrite both changes

5. Remove the conflict markers.

6. Repeat for all conflicts in the file.

7. Click Mark as resolved.
   

8. If multiple files have conflicts, repeat the steps for each file.

9. When everything is resolved, click Commit merge.
   

10. If prompted, confirm whether to update the existing branch or create a new one based on repository protections.

11. Once the conflict is resolved, you can Merge pull request as usual.

---

🟥 When You Must Resolve Conflicts Locally

GitHub cannot resolve:

• Structural changes
• File deletions
• File renames
• Complex multi-file conflicts
• Conflicts involving binary files (images, audio, etc.)

In these cases, resolve conflicts on your machine.

GitHub’s guide for local conflict resolution:
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line

---

💡 Best Practices

• Pull from develop or main frequently to prevent your branch from falling behind.
• Keep your pull requests small to reduce the risk of merge conflicts.
• Use Draft Pull Requests so conflicts are detected early.
• Communicate with teammates when working in the same file or feature area.
• Resolve conflicts locally when the changes are complex (recommended).
• After resolving conflicts, always run and test the project before pushing.
• Read conflict markers carefully and remove all of them.

---

⚠️ Common Mistakes to Avoid

Mistake	Why It Matters
Ignoring conflict warnings	Blocks your PR from being merged and slows the team
Leaving conflict markers in the code (<<<<<<<, =======, >>>>>>>)	Causes compile errors and CI/CD failures
Trying to resolve complex conflicts on GitHub	Can break logic or overwrite important code
Working on outdated branches	Greatly increases conflict frequency
Combining multiple issues into one branch	Leads to large conflict-heavy PRs
Accepting changes without reviewing both sides	Can accidentally delete important code

---

🔗 Next Step

➡️ Proceed to: PR Review Process