Merge conflicts are a natural part of collaborative development with Git. While Git can automatically merge most changes, sometimes it needs human intervention to decide how to combine conflicting modifications. This guide will help you understand what merge conflicts are, when they occur, how to resolve them, and how to minimize them in your workflow.
🎥 Video: How to Resolve Merge Conflicts in Git (7 mins) - A practical walkthrough of resolving merge conflicts
A merge conflict is a situation that occurs when Git cannot automatically determine how to integrate changes from different branches. When this happens, Git marks the conflicting areas in the affected files and requires a developer to manually resolve these conflicts before the merge can be completed.
In essence, a merge conflict is Git saying: "I'm not sure which version of this code to keep, so I need you to decide."
When a conflict occurs, Git will modify the affected files to show both versions of the conflicting code, separated by special marker lines:
<<<<<<< HEAD
This is the code from your current branch
=======
This is the incoming code from the branch you're merging
>>>>>>> feature/branch-nameDepending on your editor, the conflict might be color-coded, something like this:
<<<<<<< HEAD and ======= shows the content from your current branch (often called the receiving branch)======= and >>>>>>> feature/branch-name shows the content from the branch you're trying to merge (the source branch)Merge conflicts typically occur in the following scenarios:
The most common type of conflict happens when the same lines of a file have been modified differently in the two branches being merged.
Both branches add a file with the same name but different content.
One branch modifies a file while another branch deletes it.
One branch changes a file while another changes the directory structure containing that file.
Changes to binary files (like images) that Git can't automatically merge.
⚠️ Note: Conflicts are more likely to occur when:
- Multiple developers work on the same files
- Branches diverge for long periods before merging
- Large, sweeping changes are made across many files
Let's walk through a typical merge conflict scenario and its resolution.
Two developers are working on an HTML file. Developer A is working on the main branch, while Developer B is working on a feature branch called feature/new-header.
<!DOCTYPE html>
<html>
<head>
<title>Our Website</title>
</head>
<body>
<header>
<h1>Welcome to Our Website</h1>
</header>
<main>
<p>This is our website content.</p>
</main>
</body>
</html>header:<!DOCTYPE html>
<html>
<head>
<title>Our Website</title>
</head>
<body>
<header>
<h1>Welcome to Our Company Website</h1> <!-- Notice 'Company' -->
</header>
<main>
<p>This is our website content.</p>
</main>
</body>
</html>feature/new-header:<!DOCTYPE html>
<html>
<head>
<title>Our Website</title>
</head>
<body>
<header>
<h1>Welcome to Our Amazing Website</h1> <!-- Notice 'Amazing' -->
</header>
<main>
<p>This is our website content.</p>
</main>
</body>
</html>When Developer B tries to merge their feature branch into main after Developer A has already committed their changes:
$ git checkout main
$ git pull # Get Developer A's changes
$ git merge feature/new-header
Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Automatic merge failed; fix conflicts and then commit the result.Now, the index.html file contains:
<!DOCTYPE html>
<html>
<head>
<title>Our Website</title>
</head>
<body>
<header>
<<<<<<< HEAD
<h1>Welcome to Our Company Website</h1>
=======
<h1>Welcome to Our Amazing Website</h1>
>>>>>>> feature/new-header
</header>
<main>
<p>This is our website content.</p>
</main>
</body>
</html>The above conflict might look like this in your editor, including highlighting and buttons to accept one version or the other.
Developer B needs to decide which version to keep or how to combine them.
<!DOCTYPE html>
<html>
<head>
<title>Our Website</title>
</head>
<body>
<header>
<h1>Welcome to Our Amazing Company Website</h1>
</header>
<main>
<p>This is our website content.</p>
</main>
</body>
</html>After editing the file to resolve the conflict:
# Stage the resolved file
$ git add index.html
# Complete the merge with a commit
$ git commit -m "Merge feature/new-header, resolve heading conflict"
[main a1b2c3d] Merge feature/new-header, resolve heading conflictThe flow of resolving the conflict looks like this:
Git provides several approaches to resolve conflicts:
# See which files have conflicts
$ git status
# After manually editing conflicted files
$ git add <resolved-file>
$ git commitMost modern IDEs have built-in Git conflict resolution tools that highlight conflicts and provide buttons to accept one version or the other, as well as a way to add & commit the resolved conflict.
While merge conflicts can't be completely eliminated, you can reduce their frequency and complexity with these practices:
Always pull the latest changes from the remote repository before pushing your own changes.
$ git pull origin main
$ git push origin mainMake smaller, focused commits rather than large, sweeping changes that touch many files.
# Instead of one large commit:
$ git add .
$ git commit -m "Add user authentication, profile page, and settings"
# Better approach:
$ git add auth/*
$ git commit -m "Add user authentication"
$ git add profile/*
$ git commit -m "Add user profile page"
$ git add settings/*
$ git commit -m "Add user settings page"Don't let feature branches live too long. The longer a branch exists separately from main, the more likely it is to develop conflicts.
Regularly merge or rebase your feature branches with the main branch to reduce divergence.
# While working on a feature branch
$ git checkout feature/my-feature
$ git pull origin main # Get latest main changes
# OR
$ git rebase main # Replay your changes on top of latest mainCommunicate with team members about which files you're modifying to avoid simultaneous changes to the same areas.
Design your codebase to be modular, with separate files for separate functionality, to reduce the chances of developers needing to modify the same files.
Adopt a team-wide code formatting standard and use automatic formatters to avoid conflicts due to formatting differences.
💡 Tip: If you know you'll need to merge significant changes, communicate with your team before starting to minimize conflicts.
If a merge becomes too complex, you can abort it and try a different approach:
$ git merge --abort