Your pull request looked perfect. Then GitHub threw up that red warning: “This branch has conflicts that must be resolved.”
Learning how to resolve conflicts in GitHub is a skill every developer needs when working on collaborative projects.
Merge conflicts happen when multiple people edit the same file lines. Git cannot decide which version to keep, so it asks you to fix the problem manually.
This guide walks you through identifying conflicting files, understanding conflict markers, choosing which code to keep, and completing the merge.
Seven steps. About 15 minutes. You will handle pull request conflicts without breaking your repository or losing important code changes.
What Is a Merge Conflict in GitHub?
Resolving conflicts in GitHub is the process of manually fixing code discrepancies when Git cannot automatically merge changes from different branches.
This happens when two or more contributors edit the same lines in a file, or when one person deletes a file another person modified.
Learning how to resolve conflicts in GitHub matters for any team working on a shared codebase.
Users need this skill when pull requests show conflict warnings, when branch merging fails, or when competing line changes block a merge commit.
This guide covers 7 steps requiring 10 to 20 minutes and basic Git command knowledge.
Prerequisites
Before you start, make sure you have:
- Git version 2.30 or later installed on your machine
- A GitHub account with access to the repository
- A code editor like VS Code, Sublime Text, or IntelliJ IDEA
- Basic understanding of Git branches and commits
- Terminal or command line access
- A pull request currently showing merge conflict status
Time estimate: 10 to 20 minutes depending on conflict complexity.
Skill level: Beginner to intermediate.
Step One: How Do You Identify Merge Conflicts in GitHub?
GitHub displays a conflict warning message at the top of any pull request that has competing changes, showing “This branch has conflicts that must be resolved” with a red indicator and a Resolve conflicts button.
Action
- Navigate to: Your repository > Pull requests > Select the PR with issues
- Look for: Red banner stating “This branch has conflicts that must be resolved”
- Result: You see the Resolve conflicts button if the conflict is simple enough to fix in the web editor
Purpose
Identifying the conflict early prevents failed merges and blocked deployments.
The warning tells you exactly which files need attention before you can merge branches in GitHub.
Step Two: Where Do You Find the Conflicting Files?
Conflicting files appear in the pull request’s Files changed tab marked with a red conflict icon, and GitHub lists them specifically when you click the Resolve conflicts button in the merge section.
Action
- Click: Resolve conflicts button on the PR page
- View: Left sidebar shows all files with conflicts listed
- Check: Each file name with a warning icon needs manual resolution
Purpose
Knowing which files have conflicts lets you plan your resolution strategy.
Some PRs have one conflicting file. Others have dozens.
Step Three: How Do You Open the Conflict Editor on GitHub?
Click the Resolve conflicts button on the pull request page to open GitHub’s web-based conflict editor, which displays the file contents with conflict markers highlighting the competing changes from both branches.
Action
- Button location: Pull request > Merge section > Resolve conflicts
- Editor view: Full file content with highlighted conflict sections
- Navigation: Use the left sidebar to switch between conflicting files
Purpose
The conflict editor provides a visual way to see both versions of the code side by side.
No need to clone the repository locally for simple line-based conflicts.
When the Button Is Disabled
If Resolve conflicts appears grayed out, the conflict is too complex for the web editor.
You need to resolve it using the command line or a local source control tool instead.
Step Four: What Do the Conflict Markers Mean?
Conflict markers are special characters Git inserts into files to show exactly where competing changes exist: <<<<<<< marks your branch’s version, ======= separates the two versions, and >>>>>>> marks the incoming branch’s version.
Action
- First marker
<<<<<<< HEAD: Start of your current branch changes - Divider
=======: Separates your changes from the other branch - End marker
>>>>>>> branch-name: End of incoming branch changes
Purpose
Understanding these markers prevents accidental code deletion.
You must remove all three markers after deciding which code to keep; leaving any marker breaks the file.
Step Five: How Do You Choose Which Changes to Keep?
Review both code versions between the conflict markers, decide whether to keep your changes, accept incoming changes, or combine both into a new version that incorporates the best parts of each contribution.
Action
- Option 1: Keep only your branch’s code (delete everything from
=======to>>>>>>>) - Option 2: Keep only incoming code (delete everything from
<<<<<<<to=======) - Option 3: Merge both versions manually into combined code
- Final step: Delete all conflict markers (
<<<<<<<,=======,>>>>>>>)
Purpose
This decision determines what code ships to production.
Check with teammates through your code review process if unsure which version is correct.
Step Six: How Do You Mark the Conflict as Resolved?
After editing the file and removing all conflict markers, click the Mark as resolved button in GitHub’s conflict editor to signal that the file no longer has competing changes and is ready for merge.
Action
- Verify: No
<<<<<<<,=======, or>>>>>>>markers remain - Click: Mark as resolved button (top right of file editor)
- Repeat: Process each conflicting file listed in sidebar
Purpose
Marking files as resolved tells GitHub you finished reviewing that file.
The button stays disabled until you remove every conflict marker from the file.
Step Seven: How Do You Complete the Merge After Resolving Conflicts?
Once all files show resolved status, click the Commit merge button to create a new merge commit that incorporates your conflict resolutions, then proceed with the normal pull request merge workflow.
Action
- Check: All files in sidebar show green checkmarks
- Click: Commit merge button (green, top right)
- Return to: Pull request page > Click Merge pull request
Purpose
The commit merge creates a permanent record of your resolution decisions in the version control history.
Your PR can now complete the merge without blockers.
Verification
Confirm your conflict resolution worked correctly:
- Pull request status changes from “Conflicts” to “Ready to merge”
- No red conflict warnings appear on the PR page
- Merge pull request button becomes active (green)
- Files changed tab shows clean diff without markers
Run your continuous integration checks to verify the merged code compiles and passes tests.
Troubleshooting
Issue: Resolve Conflicts Button Is Disabled
Solution: The conflict involves file deletions or binary files that GitHub’s web editor cannot handle.
Use Git Bash or your local terminal to resolve manually with git merge and git add.
Issue: Conflict Markers Still Appear After Saving
Solution: You missed removing some markers; search the file for <<< or >>> characters.
Every marker must be deleted, not just the code between them.
Issue: Merge Fails After Marking as Resolved
Solution: New commits arrived on the base branch during your resolution.
Pull the latest changes and resolve any new conflicts that appear.
Issue: Accidentally Deleted Important Code
Solution: Use git revert to undo the merge commit, then restart the conflict resolution process.
Check git log to find the commit hash you need.
Alternative Method: Resolving Conflicts Using Command Line
GitHub Web Editor Method (Current Guide)
- Time: 5 to 10 minutes
- Complexity: Beginner
- Best for: Simple line-based conflicts in text files
Command Line Method
- Time: 10 to 15 minutes
- Complexity: Intermediate
- Best for: Complex conflicts, file deletions, binary files, multiple files
Choose the web editor for quick fixes on small PRs.
Choose command line when GitHub grays out the Resolve conflicts button or when you need to resolve merge conflicts in Git across many files.
Command Line Steps
- Fetch latest changes:
git fetch origin - Switch to your branch:
git checkout your-branch - Merge base branch:
git merge main - Check git status to see conflicting files
- Edit files, remove markers, save
- Stage resolved files:
git add filename - Commit:
git commit -m "Resolve merge conflicts" - Push to GitHub:
git push origin your-branch
Related Processes
- How to create a new branch in Git
- How to merge two branches in Git
- What is Git rebase
- How to use Git diff to compare changes
- How to delete a branch in GitHub
- How to commit to GitHub
FAQ on How To Resolve Conflicts In Github
What causes merge conflicts in GitHub?
Merge conflicts occur when two or more contributors edit the same lines in a file on different branches. Git cannot automatically determine which version to keep, so it flags the file and requires manual resolution before completing the merge.
Can I resolve conflicts directly on GitHub without using the command line?
Yes. GitHub provides a web-based conflict editor for simple line-based conflicts. Click the Resolve conflicts button on your pull request page. Complex conflicts involving file deletions or binary files require using Git locally.
What do the conflict markers mean in my code?
The <<<<<<< HEAD marker shows your branch’s code. The ======= divider separates both versions. The >>>>>>> marker ends the incoming branch’s code. Delete all markers after choosing which changes to keep.
How do I know which code version to keep during conflict resolution?
Review both versions and understand what each change accomplishes. Consult with teammates who made the competing changes. Sometimes you keep one version; other times you combine both into new code that incorporates the best elements.
Why is the Resolve conflicts button grayed out on my pull request?
GitHub’s web editor only handles simple text conflicts. The button disables when conflicts involve deleted files, binary files, or changes too complex for browser-based resolution. Use git clone and resolve locally instead.
Can merge conflicts cause data loss in my repository?
Not automatically. Git preserves both versions until you decide. Data loss happens only through user error during resolution. Use git stash to save uncommitted work before merging, and verify changes before committing.
How do I prevent merge conflicts from happening?
Pull changes from the main branch frequently. Keep feature branches short-lived. Communicate with teammates about which files you are editing. Use a clear Git workflow that minimizes parallel edits to the same files.
What happens if I commit without removing all conflict markers?
Your code breaks. The <<<<<<< and >>>>>>> markers are invalid syntax in most programming languages. Your build pipeline will fail, and the application will not compile or run correctly.
Can I undo a merge conflict resolution if I made a mistake?
Yes. If you have not pushed yet, use git reset to undo the merge commit. If already pushed, use git revert to create a new commit that undoes your changes.
Do merge conflicts affect my repository’s commit history?
Resolving conflicts creates a merge commit in your remote repository history. This commit documents how you combined the competing changes. Some teams use git squash to keep history cleaner.
Conclusion
Knowing how to resolve conflicts in GitHub keeps your team’s collaborative coding on track without delays or broken builds.
You now understand conflict markers, the GitHub conflict editor, and when to switch to command line resolution.
Branch merging issues will happen. That is normal in any active software development process.
The key is catching competing line changes early and communicating with teammates before conflicts grow complex.
Practice these steps on a test branch first. Make intentional conflicts. Fix them.
Within a few attempts, conflict resolution becomes routine rather than stressful.
Your feature branches will merge cleanly, your dev and ops teams stay aligned, and your codebase stays healthy.
Many of his resources are available on various design marketplaces and for free on Codepen.
Over the years, he's worked with a range of clients and contributed to design publications like Design Your Way, Designmodo, WebDesignerDepot, WPDean, Speckyboy, and Slider Revolution among others.
