I’ve been running an Intro to Open Source workshop for a couple of months now, and one of the biggest challenges for participants often dealing with is keeping their branch up to date and managing merge conflicts. Listen, if you see that “merge conflicts” message and you panic, you’re not alone. I may or may not have used the strategy of deleting my entire local repository, forking, recloning, and redoing my code to avoid navigating merge conflicts more than once. Luckily, there are much better ways of dealing with updating your branch and merge conflicts than that. If you’ve ever felt that panic and wanted to burn it all down, take a deep breath and read the post below that walks you through the process of keeping your branch up to date while waiting for reviews. Keeping your branch in sync with the main repository helps to avoid conflicts and create a smooth(er) merging process.
If you want to follow the steps below, I’ll be focusing on the scenario where you've forked and cloned the guestbook repository and are adding yourself using a CLI tool, but this is generally applicable to staying up to date.
Identifying Merge Conflicts
Before making any updates to your branch, it's important to check for merge conflicts. Merge conflicts occur when changes in the branch of the repository that you're asking to merge into conflict with your local changes.
When you create a pull request to merge your changes into a specific branch of the repository, Git will check for conflicts between your changes and the latest changes in that specific branch. If there are conflicting changes, Git will raise a merge conflict, indicating that manual intervention is required to resolve the discrepancies between the two sets of changes.
To identify merge conflicts, follow these steps:
- Ensure you are on your feature branch–the branch you’re trying to merge your changes into:
git checkout <your-feature-branch>
- Fetch the latest changes from the main repository:
git fetch upstream
- Compare your branch with the main repository's main branch:
git diff <your-feature-branch> upstream/main
Any conflicting lines will be highlighted in the output, indicating potential merge conflicts.
For our guestbook repository, if you’ve created a PR, you can scroll to the bottom of the PR and see whether or not you have conflicts. If you do, it will look like this if you have conflicts:
Keeping Your Branch Updated
To keep your branch up to date with the latest changes from the main repository, there are a couple of different approaches. I think GitHub has a really user friendly way to keep it updated.
When you look at your fork, it will let you know if you’re behind. If you are, you can choose to sync your fork with the branch you’ve forked off of like this:
If you want to use git, you can do it like this:
- Stash or commit your local changes (if any):
git stash save "Your descriptive stash message" # Or commit your changes
- Pull the latest changes from the main repository's master branch:
git pull upstream <branch you’ve forked off of>
- Apply your stashed changes (if any) back to your branch:
git stash apply
If you want to learn more about Git commands, check out the previous post.
Resolving Merge Conflicts
After pulling the latest changes, Git may detect conflicts between the changes you’ve made and the main repository's changes. I want to emphasize that if you see merge conflicts, don’t feel like you’ve done something wrong. There’s a roadblock, and now you just need to figure out how to unblock it. For example, you might see something like this:
Here are some steps you can use to resolve merge conflicts:
- Remember, conflicts are a natural part of collaboration. Open the conflicted files using a text editor and look for the conflict markers (<<<<<<<, =======, and >>>>>>>) to understand where the conflicting changes are.
- Edit the conflicting section, removing the conflict markers and deciding which changes to keep. Create a version that incorporates the best of both changes if that aligns with the project's goals.
- After resolving conflicts, save the file and stage it.
git add <conflicted-file>
- Commit the changes.
git commit -am "Resolve merge conflicts with upstream"
Preparing Your Pull Request
As you work through the issue and keep your branch updated, your pull request should be in good shape for merging. A couple of things to keep in mind:
Test your changes and add relevant documentation.
Make your pull request descriptive and provide context for the changes you've made–you can use the OpenSauced chrome extension to generate the first draft of your PR description!
Sync your fork and/or rebase your feature branch on the latest upstream branch before creating the pull request.
git fetch upstream
git rebase upstream/main
Submitting Your Pull Request
With your branch up to date and conflicts resolved, it's time to submit your pull request. The maintainers of the repository will review your changes and, if everything looks good, merge them into the main repository.
When you’ve submitted your PR to our repository, you should see all checks passing and no indications of merge conflicts, like this:
Handling Feedback
Be prepared to receive feedback from the maintainers and community members. This is an opportunity to improve your contribution and to showcase your communication skills. Make the necessary updates based on the feedback and push them to your feature branch. The pull request will automatically update with the new changes.
If you want to learn more about what happens when you submit pull requests, check out:
You might find that you need to update your branch more than once when you’re waiting to get your PR merged. That’s ok. What’s important is that you know how to do it now. By following these steps, you can contribute without that panic of not knowing what to do when you see that merge conflict message. If you still panic a little, that’s ok. And if you try to fix it and you’re still having trouble, reach out to a community, a maintainer, or a mentor. There’s lots of people out there willing to help. You just need to ask for it.
Top comments (6)
Thanks for covering this! It troubled me so much as a new contributor.
Great article @bekahhw !
I remember the first time I ran into a merge conflict and I thought I did something wrong.
This is super helpful information for those just getting started. 😄
Thanks, Jessica! I had the same experience and I was super panicked.
Well done!
Thanks for this post @bekahhw! 😊 Solving merge conflicts are something that I’m trying to solve, so I’ll definitely try these steps.
Awesome! If it doesn’t help, let me know and maybe we can pair up.