Beginner’s guide to GitHub: Merging a pull request

Welcome back to GitHub for Beginners, a series designed to help you navigate GitHub with ease.

So far in this series, we’ve covered the top Git commands every developer should know, how to create repositories, how to upload files and folders to your repository, how to add code to your repository, and how to create your first pull request. However, sometimes it can be a little bit more complicated when changes conflict with each other. As you will see, GitHub has tools to help you navigate this potentially confusing situation.

Let’s get started!

Pull request recap

First, let’s review what a pull request is (often referred to as a PR) and how it works. A pull request is a proposal to move a set of changes from one branch into another. After submitting a pull request, other team members can review your proposed changes before accepting them. They can review your code, test your changes locally, and provide feedback.

Once you have completed the review process, you can merge the changes into the target branch on GitHub by clicking the green button that says “Confirm merge.” This pulls the changes into the target branch, making your proposed updates.

What are merge conflicts?

Sometimes, GitHub can’t automatically merge the changes into the target branch. This usually happens because of a merge conflict.

Since the same section of the file changed, GitHub doesn’t know which version of the changes you want to keep, so in order to merge a pull request on GitHub, you must first resolve all merge conflicts.

Creating a merge conflict

To show you how to resolve a merge conflict, it’s helpful to create one and walk through the steps necessary to fix it. For this example, we are working in this repository. We already have a pull request in this repository under the update-name branch to update the index.html file with a change to the header text. What we’re going to do is create a new branch for this repository and introduce a different change to the same section of the index.html file.

Open your terminal and navigate to the project directory for this repository. If you need help with these steps, refer to the earlier entries in the GitHub for Beginners guide. Once you’re in your project directory, run git checkout -b add-new-name to create a new branch named add-new-name. In the new branch, open the index.html file and change the header text to be a different title from the existing pull request. Save the file and exit your editor.

Now that the changes have been made, you need to push them by running git push origin add-new-name in the terminal.

Navigate to the repository on GitHub and create a pull request for the add-new-name branch, pulling the changes into the main branch. Don’t forget to finish the merge by clicking the green “Confirm merge” button on the pull request page. Now, these changes have been integrated into the **main **branch of the repository.

Make your way back to the original pull request from the update-name branch. If you scroll to the bottom of the page, you will see that you no longer have the option to merge the changes into the main branch. Instead, you’ll see a message that there’s a merge conflict that needs to be resolved.

Resolving the merge conflict

There are a couple of ways that you can resolve merge conflicts. One option is to click the “Resolve conflicts” button on the pull request page. You can also address the merge conflicts locally by pulling down the latest changes in the target branch. We’re going to walk through the second option.

In your terminal, run git switch main to navigate to the main branch. In that branch, pull down the latest changes by running the git pull origin main command. Now, navigate back to your update-name branch by running git switch update-name in the terminal.

Run git merge main to attempt to merge the changes from update-name into main. You’ll receive a message in the terminal that the automatic merge failed and that you need to resolve the conflicts before you can continue merging. To fix the changes, open up index.html in your code editor of choice.

Depending on your code editor, the problematic section might be highlighted. If you’re using a code editor with integrated GitHub support, such as VS Code, you’ll see some options at the top of the highlighted section.

If so, click the option that says “Accept Current Change.” This will edit the file so that only the incoming change remains in the file.

If your code editor doesn’t have integrated GitHub support, you will need to manually edit the file to remove the conflicting sections. They can be easily identified by the presence of several angle brackets (that is, <<<<<<< at the start of the conflict and >>>>>>> at the end of the conflict).

Once you’ve finished editing the file, save your changes and quit the code editor. Back in the terminal, run the following commands to commit your changes and verify that all of the changes have been committed:

git add .
git commit -m "resolve merge conflict"
git status

Finally, it’s time to push these changes up to GitHub. You do this by running the git push origin update-name command. This uploads the changes that have resolved the merge conflicts into your pull request. If you navigate back to the pull request on GitHub, you’ll see that the conflicts no longer exist and that you can merge the changes into the main branch by clicking the green “Merge pull request” button. Last but not least, don’t forget to click the “Confirm merge” button.

Congratulations! You’ve resolved the conflict and updated the main branch with the requested changes!

Your next steps

If you want to practice creating pull requests and resolving merge conflicts, you can use this repository and follow the instructions in the README.md file.

Merging pull requests is an essential skill in order to be proficient with using GitHub as a collaborative development tool. However, with some practice, resolving conflicts will feel as natural as pushing changes to GitHub.

If you have any questions, pop them in the GitHub Community thread and we’ll be sure to respond.

Here are some more resources to help you on your GitHub journey:

• GitHub Foundations Certificate
• Hello world – a full pull request workflow
• Merging a pull request
• About merge conflicts
• Requesting a pull request review
• About pull requests

Written by

Kedasha Kerr

@ladykerr

Kedasha is a Developer Advocate at GitHub where she enjoys sharing the lessons she's learned with the wider developer community. She finds joy in helping others learn about the tech industry and loves sharing her experience as a software developer. Find her online @itsthatladydev.