Pull requests and merge conflicts
A pull request (PR) is a proposal to move a set of changes from one branch to another. Once submitted, teammates can review the code, test the changes locally, and give feedback. When the review is done, merging the PR on GitHub pulls those changes into the target branch.
Sometimes GitHub can’t merge automatically. That happens when two branches have different changes to the same section of a file—a merge conflict. When the same part of a file changed in both branches, GitHub has no way to know which version to keep. So before a PR can be merged, all conflicts must be resolved.
Reproducing a conflict
A merge conflict is easiest to understand if you create one. In this walkthrough, a repository already has a PR from the update-name branch that changes the header text in index.html. To create a conflict, introduce a different change in the same spot from another branch.
In the terminal, navigate into the project directory and run git checkout -b add-new-name to create a new branch. In that branch, edit the header text in index.html to a different title from the one in the existing PR, save the file, and push the branch with git push origin add-new-name.
Now open the repository on GitHub and create a PR from add-new-name into main. Finish the merge by clicking the green “Confirm merge” button. At this point, the new changes are part of main.
Instead of completing the merge, you could simply move on. But with the main branch now updated, you can also try to merge update-name into it. Make your way back to the original PR from the update-name branch. At the bottom of the page, you’ll no longer see a merge option. Instead, the page tells you there’s a conflict that has to be resolved.
Resolving conflicts locally
Merge conflicts can be handled directly on GitHub with a “Resolve conflicts” button, or they can be addressed locally by pulling the latest target-branch changes and merging them into your feature branch. The local route goes like this:
- Run
git switch mainto head to the target branch. - Pull the latest changes from GitHub with
git pull origin main. - Switch back to your feature branch with
git switch update-name. - Run
git merge mainto bring the target branch into your branch.
The terminal reports that the automatic merge failed. Open index.html—the area of conflict is highlighted depending on the editor. VS Code and similar editors with GitHub integration give you clear choices like “Accept Current Change,” which automatically keeps the incoming change and removes the other version. Editors without that integration require you to edit the file manually. You can find the conflicting sections by looking for the marker <<<<<<< at the start and >>>>>>> at the end of each conflict.
Once the file reads as you want it, save and close it. Then commit and check that everything’s in order:
git add .
git commit -m "resolve merge conflict"
git status
Push the resolved changes to GitHub with git push origin update-name. Back on the pull request page, the conflict is gone and the merge button is active again. Clicking “Merge pull request” and then “Confirm merge” brings the changes into main.
Practice makes it routine
The GitHub project at the official resolve-merge-conflicts repository has a practical exercise for learning how to fix these situations. Working through one or two deliberate conflicts makes the process much easier the next time it comes up in real collaboration. Resolving conflicts is a core skill for anyone using GitHub as part of a team—once you’ve done it a few times, it’ll feel just like any other part of the workflow.
