I don’t think I’m alone in saying this; early in my career, merge conflicts were the bane of my existence (particularly in 2019). I graduated from a coding boot camp in 2018, and during that time, if I ever experienced a git issue that I didn’t know how to fix, I would create a new repository and start over. In 2019, I started working as a software engineer with a team of other software engineers, so I couldn’t create new repositories to avoid this inconvenience. I had to face my fears and fix merge conflicts. No exaggeration; the experience would bring me to tears. See the screenshot below of me making a self-deprecating joke about mishandling merge conflicts on July 14, 2019.
Fortunately, today, I’m more comfortable with resolving merge conflicts. It still stresses me out a bit, but I have a few tips and tricks I use to resolve the situation.
Prerequisites to resolving a merge conflict
Breathe
It’s okay. Conflicts happen. You’re not the first person to experience a merge conflict. Everyone experiences merge conflicts frequently regardless of their seniority. It’s a common occurrence in version control.
Understand why merge conflicts happen
Version control systems, like Git, auto-magically manage code contributions. It identifies the change, when it was made, who made it, and on what line so that developers can easily track the history of their codebase. However, Git sometimes gets confused in the following situations:
- When more than one person changes the same line in a file and tries to merge the change to the same branch
- When a developer deletes a file, but another developer edits it, and they both try to merge their changes to the same branch.
- When a developer deletes a line, but another developer edits it, and they both try to merge their changes to the same branch
- When a developer is cherry-picking a commit, which is the act of picking a commit from a branch and applying it to another
- When a developer is rebasing a branch, which is the process of moving a sequence of commits to a base commit
Git is unsure which change to apply, so it leans on the developer for help and notifies them of a merge conflict. Your job is to help Git determine which proposed change is most accurate and up to date.
Resolving Merge Conflicts
In Visual Studio Code (or IDE of your preference)
Read the logs
When you run git merge and a merge conflict occurs, your terminal or command prompt will respond with a message like:
CONFLICT (content): Merge conflict in [filename]
This message means a conflict occurred in this particular file.
Find the conflict
Navigate to the file that Git indicated had a merge conflict and scroll through the file until you find the conflict. Your IDE may indicate where the merge conflict occurred by highlighting the changes the conflicting changes made to the file. The below example shows how VS code may highlight the conflicting changes. VS Code highlights the current change and the incoming change.
The current change (sometimes called an outgoing change) represents the code changes that you made on your local branch.
The incoming change represents the code changes you are pulling in from the base branch or modifications made by other developers.
Decide which changes need to be applied
Deciding if you want to accept current changes, incoming changes, or all the changes depends on the ultimate goal for your program. This part is up to you, your knowledge of what changes are needed, and your team.
If you’re unsure which changes to accept, it’s best to consult with your team or developer who wrote the incoming changes. You can accept changes without committing the code and test program locally for a sanity check.
Remove any lingering ==== , <<<<, or >>>> symbols
Those symbols are used to help you determine where the merge conflicts occurred. When you accept the preferred changes, those symbols usually disappear, but sometimes a glitch happens, and they don’t disappear. You don’t want accidentally commit those symbols if they persist in the file because that can create bugs in your program.
What if I make a mistake?
If you make a mistake or you’re not confident which the decision change to accept, you can stop the merge process by running the following command:
`git merge -- abort`
After you do that, don’t sit there and get frustrated. Reach out to a teammate (preferably one whose code is conflicting with yours or an engineer you can trust) and explain the situation saying: “Hey, I’m experiencing a merge conflict when I try to merge my code. I’m not feeling confident about which changes I should accept. Do you have any availability to pair with me for a few minutes?”
If you’re feeling confident about the resolved merge conflict, commit the changes
After you accept the necessary changes and you’re ready to commit the change, you can take the following steps:
- Save the files where changes were made
- Run
git statusto ensure the right files were changed - Run
git add [file name]to add the files you changed to staging - Run
git commit -m “[add your commit message here]”to commit your changes - And then run
git push
On GitHub.com
Identify which files have a merge conflict
When you open a PR on GitHub, it will let you know that there are merge conflicts and which files have conflicts.
Find the conflicts
To find the conflicts, click ‘Resolve conflicts’, and it will lead you to the files with conflicts.
Decide which changes need to be applied
The GitHub Web UI will highlight the conflicting changes with yellow and the following symbols: <<<<< ====, >>>>.
It will also indicate which branch those changes are coming from. This should help you determine which changes you want to accept.
Deciding if you want to use the changes from your branch, the base branch, or both depends on the ultimate goal for your program. This part is up to you, your knowledge of what changes are needed, and your team. Delete the lines you don’t want and keep the ones you do want.
Remove any lingering ==== , <<<<, or >>>> symbols
Those symbols are used to help you determine where the merge conflicts occurred.You don’t want accidentally commit those symbols because that can create bugs in your program.
If you’re feeling confident about the resolved merge conflict, commit the changes.
Once you remove the conflicting changes and any symbols used to highlight the conflicting changes, click ‘Mark as Resolved’ and click the ‘Commit merge’ button to commit your changes.
You can read more about merge conflicts and how to resolve them on GitHub’s official documentation.
Comment below if you have follow-up questions! Share this post if you find it helpful.
Top comments (24)
I am glad that I can use a proper IDE, working with JetBrains-IDEs make this stuff so much easier, where you have full Git integration with a proper side-by-side diff-view and can apply or dismiss changes with a single click.
Using Jetbrains products' git integration is like having a dishwasher instead of doing dishes by hand. You really can't live without it once you have it, because it makes life so easy! It's simply amazing!
Oh wow! Okay, I'm sold!
Interesting! I'll have to look into how JetBrains does it. I wouldn't describe VS code as hard. They have the option to see it side by side. You can apply and dismiss the changes in one click there as well, but if you're newer to version control ..the terminology of "current changes" or "incoming changes" can seem confusing.
Here's a post about the different ways to handle merge conflicts in different IDEs..might be interesting to compare those to JetBrains: betterprogramming.pub/how-to-resol...
I think this is THE reason why I've never really switched to VSCode. And I cannot understand why is so difficult to provide a plugin that handles the conflicts like JetBrains-IDEs do.
I mean, there's gitlens on VScode.. you can compare your code with the last commit and easily handle conflicts.
My last group project in my coding bootcamp was a nightmare only because daily we were having merging conflicts, so it's safe to say the fear is now gone lol! But this article did provide some new insight to how to better manage and prevent these hiccups from happening in the first place! Not always avoidable, but definitely manageable. Thank you Rizèl ✨
Lol, glad you got that experience in your group. While it was probably frustrating, now you're more prepared for future situations. Definitely manageable, and there's actually ways to avoid it or have less merge conflicts. Maybe I will write about that soon. And thank you for reading and commenting!
Whaaatt??!! Then yes, yes, yes please write about it! And of course your content is engaging and informative, best of both worlds!
Just be glad you didn't use Microsoft Visual SourceSafe. The merging was ok for the time but having to chase down someone on holiday to unlock a checked out file was a nightmare. Then the "database" would corrupt.
LOL I'm grateful I never experienced that
Awesome and helpful writeup😃💯
I'm glad it was! Let me know if you have any other questions.
Update: here's my thoughts on preventing merge conflicts -
dev.to/github/how-to-prevent-merge...
A few principal notes.
1. You (among with most of such recipesʼ authors) have omitted one principal thing: in a complex case, to understand how a conflict should be resolved, you might see an original base of each conflicting chunk. To make it visible in conflicts, use setting:
git config merge.conflictStyle diff3(you may add--globalfor global setting).This will add a new section, like in the following example:
original:
version1:
version2:
After merge attempt:
You see new section after
||||||||- this is the common base.Not only a human gets aid from it - this is crucial for automated merge tools.
2. Next: use automated merge tools. There are lots of them: kdiff3, vimdiff... They have two merits: 1) they are deliberately smarter than default git logic and may resolve conflicts that git retains unresolved; 2) they provide visual interface to merge.
For a command in git, this is
git mergetool(shall be configured, what tool to run).3. Use aid to understand what change is applied now to make the conflict. Depending on operation, this could be
git statusplusgit showfor specified commit id (shows the applied patch - typical for rebase),git am --show-current-patch(I use aliasgit amshfor it; used for cherry-pick as well).4. Notice that sometimes git misdetects what chunks to compare. You might need editor to relocate code blocks to realize the proper relation between chunks. I usually experienced this in case of sequence of small methods when something is inserted inside the sequence.
+1 to calling in the other author you're conflicting with. on the command line a merge conflict looks and is arcane, cryptic, and math-heavy. but the reality is that it's just you and another person collaborating asynchronously.
You worded that well!
Good article! It might be worth mentioning that as well as accepting current and/or incoming changes you can just grab code from each change and manually edit what you want to keep/remove (at which point manually removing the change indicators is also required).
Obviously the best strategy is to avoid merge conflicts in the first place. That's achieved by careful planning; good communication between team members; and can also be mitigated by keeping up with the base branch (i.e. rebasing regularly).
How to handle merge conflicts in Pulling remote changes to a local repository ? powerful dua for marriage with a loved one
I switched from Vscode to Meld to solve conflicts, give it a try: it's very handy and visual