What Is a Git Merge Conflict? How to Resolve It

26 min read

What Is a Git Merge Conflict?

A Git merge conflict occurs when Git cannot automatically combine changes from different branches because the changes overlap or conflict with one another. Understanding what is a Git merge conflict is essential for developers who work with version control, collaborate on shared repositories, manage feature branches, and contribute to open-source projects. Git provides powerful tools to combine code, but when two branches contain conflicting changes, developers must decide how to integrate those changes correctly.

This guide explains merge conflict causes, Git merge conflict examples, and how to resolve merge conflicts in Git step by step. You will learn Git conflict resolution commands, how to resolve conflicts in GitHub, GitLab, and Bitbucket, how to fix conflicts in popular code editors, and how to prevent merge conflicts when working in teams. Whether you are learning Git for the first time or troubleshooting a complex repository, this tutorial will help you understand the complete Git conflict resolution workflow.

What Is a Git Merge Conflict?

A Git merge conflict happens when Git cannot determine which changes should be preserved while combining two branches, commits, or sets of modifications. Git usually merges independent changes automatically. However, when different branches modify the same lines of a file or introduce incompatible changes, Git pauses the operation and asks the developer to resolve the conflict.

For example, imagine two developers working on the same application. Developer A changes a function to calculate a product discount, while Developer B changes the same function to calculate a tax. If both changes affect the same lines, Git might not know whether to retain the discount calculation, the tax calculation, or a combination of both.

This situation is known as a content conflict. Git identifies the affected files, marks the conflicting sections, and waits for a developer to make the appropriate decision.

A merge conflict does not necessarily mean your repository is damaged. It is a normal part of the Git collaboration workflow, especially when multiple developers work on the same source code and configuration files.

Why Does Git Need Manual Conflict Resolution?

Git uses the common ancestor of two branches and compares their changes to determine how to combine them. If the modifications can be applied independently, Git generally merges them automatically.

However, Git cannot reliably understand the intended behavior of every application. Two lines might be syntactically valid but logically incompatible. Consequently, Git requires a developer to inspect the changes and determine the correct result.

What Causes a Git Merge Conflict?

Understanding merge conflict causes helps developers identify problems before they become difficult to resolve. Several situations can produce conflicting changes.

1. Modifying the Same Line in Two Branches

The most common cause occurs when developers modify the same line in different branches.

Suppose the original code is:

const timeout = 5000;

One branch changes it to:

const timeout = 3000;

Another branch changes it to:

const timeout = 10000;

When Git attempts to merge the branches, it cannot determine which timeout value the application should use. A developer must select the appropriate value or implement a different solution.

2. Delete/Modify Conflict

A delete/modify conflict occurs when one branch deletes a file while another branch modifies that file.

For example, one developer removes an outdated configuration file, while another updates its settings. Git needs a decision about whether the file should remain in the repository.

3. Add/Add Conflict

An add/add conflict happens when two branches independently create a file with the same path but different contents.

For instance, both developers create config.js, but each file contains different application settings. Git cannot automatically determine which version represents the intended configuration.

4. Rename Conflict

A rename conflict occurs when branches rename the same file differently or when a rename interacts with other modifications.

For example, one branch renames user.js to account.js, while another renames it to profile.js. Resolving this conflict requires choosing the appropriate filename and ensuring that imports and references are updated.

5. Binary File Conflicts

Binary file conflicts can involve images, compiled assets, PDFs, audio files, or other files that Git cannot merge meaningfully as ordinary text.

Developers may need to choose one version, edit the file using an appropriate application, or regenerate the asset from its original source.

6. Changes to Dependencies and Configuration Files

A merge conflict in package.json, package-lock.json, yarn.lock, or pnpm-lock.yaml can occur when developers add, remove, or update dependencies in different branches.

These files require special care because choosing an arbitrary version may introduce incompatible dependency versions or inconsistent lockfile data.

Git Merge Conflict Examples

The following Git merge conflict examples demonstrate how Git represents conflicting changes and how developers can resolve them.

Example 1: A Conflict in Source Code

Imagine the original file contains:

function getMessage() {
  return "Hello";
}

Branch A changes the message to "Hello, developer!", while Branch B changes it to "Welcome to the application!".

During a conflicting merge, Git may produce the following:

function getMessage() {
<<<<<<< HEAD
  return "Hello, developer!";
=======
  return "Welcome to the application!";
>>>>>>> feature-welcome
}

These special lines are called conflict markers (<<<<<<<, =======, >>>>>>>).

• <<<<<<< HEAD identifies the beginning of the current branch’s conflicting section during a typical merge.
• ======= separates the competing versions.
• >>>>>>> feature-welcome marks the end of the incoming section and may include its branch name.

The exact labels depend on the operation and configuration. During a rebase, the current and incoming sides can be interpreted differently from a typical merge.

To resolve the conflict, decide what the function should return. You could retain one message or combine the intended behavior into a new implementation.

For example:

function getMessage() {
  return "Welcome, developer!";
}

Remove all conflict markers and verify that the resulting function behaves as expected.

Example 2: A Conflict in Configuration

Consider a configuration file with a timeout setting. One branch changes the timeout to 3,000 milliseconds, while another changes it to 10,000 milliseconds.

The conflict might appear as:

<<<<<<< HEAD
timeout=3000
=======
timeout=10000
>>>>>>> feature-settings

You should examine the application’s requirements and select the correct value. Do not simply choose the first version because it appears at the top.

Example 3: A Conflict in a Dependency File

Suppose two developers update different dependencies in package.json. Git may report a conflict if the changes overlap within the file.

A valid resolution might need to retain both dependency updates rather than choosing one branch’s entire version.

After resolving package.json, regenerate or update the relevant lockfile using the package manager appropriate to the project. Then run the project’s tests to confirm that the dependency changes remain compatible.

How to Resolve Merge Conflicts in Git

Learning how to resolve merge conflicts in Git becomes easier when you follow a consistent process. The following step-by-step merge conflict tutorial demonstrates the usual workflow.

Step 1: Check Your Repository Status

Start by running:

git status

The git status command displays the current branch, modified files, staged changes, and unmerged paths.

When a merge conflict occurs, Git typically identifies the files that require attention. You might see a message such as:

Unmerged paths:
  both modified: src/app.js

This indicates that Git cannot complete the merge until the conflict is resolved.

Step 2: Review the Changes

Use the following commands to understand the repository’s history and differences:

git diff
git log --oneline --graph --all

The git diff command helps inspect differences in your working tree. During a conflict, it can show conflict markers and other changes that have not been staged.

The git log command helps you understand which commits were made and how the branches diverged. You can also inspect individual commits when additional context is needed.

For more detailed information about your repository’s state, examine the relevant branch history before changing files.

Step 3: Open the Conflicting Files

Open each file identified by git status. Search for the conflict markers:

<<<<<<<
=======
>>>>>>>

Read both versions carefully and determine which changes are required. A conflict may affect multiple files, so resolve each file rather than assuming that fixing the first one completes the entire operation.

Step 4: Manually Edit Conflict Markers

To manually edit conflict markers, remove the markers and replace the conflicting section with the correct final implementation.

For example, change this:

<<<<<<< HEAD
const greeting = "Hello";
=======
const greeting = "Welcome";
>>>>>>> feature-greeting

Into this:

const greeting = "Welcome";

Alternatively, if both changes are necessary, combine their logic:

const greeting = "Welcome";
const audience = "developer";

The correct result depends on the application requirements. Always review the surrounding code to ensure that the resolution preserves the intended behavior.

Step 5: Stage the Resolved Files

After resolving a file, use:

git add src/app.js

The git add command stages the resolved file and tells Git that you have addressed its conflict.

If multiple files were resolved, stage each one individually or stage the appropriate paths. Avoid staging unrelated changes unintentionally.

Run git status again to verify that no unresolved conflicts remain.

Step 6: Complete the Merge

For a regular merge, once all conflicts are resolved and staged, complete the operation with:

git commit

Git may provide a default merge commit message. Review it and save the commit to finish the merge.

If the merge was initiated through a tool that manages commits automatically, such as some web interfaces or IDE workflows, follow that tool’s instructions instead.

Step 7: Test the Application

After resolving conflicts, run the project’s tests, linting tools, build process, and other relevant checks.

For a JavaScript project, these commands might include:

npm test
npm run lint
npm run build

Use only the scripts that are defined in your project’s package.json. If the project uses another package manager or build system, follow its documented workflow.

Testing is essential because Git verifies that changes can be combined at the file level, not that the resulting program is logically correct.

Essential Git Merge Conflict Commands

The following Git merge conflict commands are useful for diagnosing, resolving, and recovering from conflicting changes.

Understanding git fetch and git pull

The git fetch command downloads updates from a remote repository without automatically merging those updates into your current branch.

The git pull command fetches updates and then integrates them according to your Git configuration, commonly through a merge or rebase. A Git pull conflict can occur when the incoming changes cannot be integrated automatically.

A safer troubleshooting approach is to fetch first, inspect the incoming changes, and then decide how to integrate them.

Using git merge --abort

If a merge becomes complicated and you want to cancel it, run:

git merge --abort

This attempts to return the repository to its pre-merge state. However, it may not fully restore work that was already present or changed during the merge, especially if the working tree contained uncommitted changes beforehand.

For that reason, commit or back up important work before beginning risky operations.

Understanding git restore and git reset

The git restore command can restore file contents or update the staging area. It is useful for targeted recovery, but careless use can discard changes.

The git reset command can move the current branch reference or modify the staging area, depending on the selected mode. Some reset operations can make commits harder to find through normal branch history.

Neither command should be used blindly to remove a conflict. First determine whether you want to preserve, discard, or reorganize the affected work.

Choosing Between Current and Incoming Changes

When resolving a conflict, you may need to choose between the current and incoming versions.

The current side is commonly associated with HEAD during a standard merge. The incoming side represents the changes being merged into the current branch. These meanings can differ during rebasing, so check the operation before selecting a version.

Using git checkout --ours

For a supported merge conflict, you can select the current branch’s version of a file:

git checkout --ours -- src/app.js
git add src/app.js

This is useful when the current version should be preserved entirely. However, it discards the incoming version of that file from the working resolution, so use it only when that is the intended outcome.

Using git checkout --theirs

To select the other side of the conflict during a supported merge, run:

git checkout --theirs -- src/app.js
git add src/app.js

This selects the incoming version for that path. During a rebase, the meanings of ours and theirs can be counterintuitive because Git replays commits onto another base.

How to Accept Both Changes

Accepting both changes means combining the useful parts of each version into one valid result. It does not necessarily mean copying both sections exactly as they appear.

For example, if one branch adds input validation and another adds error handling, the best resolution may preserve both features in a single function.

After combining changes, inspect the code for duplicate declarations, inconsistent assumptions, incorrect imports, and incompatible function signatures.

Common Types of Git Conflicts

Not every conflict involves the same kind of operation. Recognizing the type of conflict helps you select the appropriate resolution strategy.

Git Rebase Conflict

A Git rebase conflict occurs when Git cannot replay a commit onto the target base without manual intervention.

To resolve conflicts during rebasing:

1. Inspect the files using git status.
2. Edit the conflicting sections.
3. Stage the resolved files using git add.
4. Continue the rebase using git rebase --continue.

If you decide to cancel the operation, use:

git rebase --abort

A rebase can replay several commits, so a conflict may occur more than once. Avoid rewriting shared branch history without coordinating with your team.

Git Cherry-Pick Conflict

A Git cherry-pick conflict occurs when a selected commit cannot be applied cleanly to the current branch.

Inspect the conflicting files, resolve the changes, and stage the results. Then continue the operation with:

git cherry-pick --continue

To cancel an in-progress cherry-pick, use:

git cherry-pick --abort

Cherry-picking is particularly useful when applying a specific fix to another branch, but developers must ensure that the selected commit’s dependencies are also present.

Git Stash Conflict

A Git stash conflict can occur when you restore saved changes that overlap with changes already present in your working tree.

For example, running git stash pop may produce conflicts if the same lines were changed after the stash was created.

Resolve the affected files, stage them, and verify the repository status. If conflicts occur, the stash entry is generally retained rather than being dropped automatically, so check git stash list before attempting another restoration.

Git Branch Conflict

A Git branch conflict occurs when Git cannot automatically integrate changes from different branches. This often happens when feature branches remain separate for a long time or when multiple contributors edit the same files.

The best solution is to inspect the branches’ histories, resolve the affected files, and test the integrated result before merging the work into a shared branch.

Git Push Rejected

A Git push rejected error is not always a merge conflict. It often occurs because the remote branch contains commits that your local branch does not have.

You may need to fetch the remote changes and integrate them before pushing again. If the integration produces conflicts, resolve them using the appropriate merge or rebase workflow.

Avoid using force-push commands as a shortcut because they can overwrite shared history and disrupt other contributors.

How to Fix Merge Conflicts in Popular Code Editors

Graphical editors provide useful tools for understanding and resolving conflicts without manually editing every marker.

Fix Merge Conflicts in VS Code

Visual Studio Code provides an integrated merge-conflict interface for supported Git operations.

To fix merge conflicts in VS Code:

1. Open the repository in VS Code.
2. Open the Source Control panel.
3. Select a file containing a conflict.
4. Review the available options, such as accepting the current change, accepting the incoming change, accepting both changes, or comparing the versions.
5. Edit the resulting code if necessary.
6. Save the file and stage the resolved changes.
7. Complete the merge or rebase using the appropriate workflow.
8. Run tests and verify the result.

These options make conflict resolution easier, but they do not determine which version is correct for your application.

Resolve Conflicts in IntelliJ IDEA

IntelliJ IDEA includes a visual merge-resolution interface that allows developers to compare conflicting versions side by side.

To resolve conflicts in IntelliJ IDEA, open the Git conflict-resolution interface, inspect the source and target changes, and select or edit the required sections. Apply the resolution, confirm that no conflicts remain, and complete the pending Git operation.

This approach is especially useful when working with Java applications, large projects, and repositories containing multiple related source files.

Using git mergetool

You can also run:

git mergetool

Git opens the configured merge tool for the conflicting files. Depending on your setup, the tool may display the base version, the current version, the incoming version, and the final result.

Review the merged output before staging and committing the files. A graphical tool can simplify comparisons, but the final resolution still requires your judgment.

How to Resolve Conflicts in GitHub, GitLab, and Bitbucket

Web-based repository platforms help teams collaborate on branches and pull requests. However, a merge conflict may need to be resolved locally when the platform cannot safely combine the changes.

Resolve Conflicts in GitHub

GitHub pull request conflicts occur when a pull request’s source branch cannot be merged cleanly into its target branch.

For simple conflicts, GitHub may offer a browser-based conflict editor. Open the pull request’s conflict-resolution interface, review the conflicting sections, edit the final content, and mark the conflicts as resolved before committing the changes.

For complicated conflicts, clone the repository or use your existing local checkout. Fetch the relevant branches, merge the target branch into the feature branch or rebase according to your team’s policy, resolve the conflicts, and push the updated branch.

Always review the pull request and run the relevant checks before merging.

GitLab Merge Conflicts

GitLab merge conflicts can arise when changes in a source branch overlap with changes in the target branch.

For supported conflicts, GitLab may provide a web editor. For more complex cases, use a local repository to inspect the changes, resolve the files, and push the updated source branch.

Check the merge request’s pipeline results and code-review feedback to ensure that the resolution meets project requirements.

Bitbucket Merge Conflicts

Bitbucket merge conflicts occur when a pull request contains changes that cannot be integrated automatically. Depending on the repository configuration and interface, some conflicts may be handled through the web interface, while others require local resolution.

Use the repository’s documented merge strategy, resolve the conflicting files, push the corrected branch, and verify the pull request before completing the merge.

Resolving Conflicts in Package and Lock Files

Dependency conflicts deserve special attention because apparently minor changes can affect the entire application.

Merge Conflict in package.json

The package.json file defines project metadata, scripts, and dependencies. If two branches add different dependencies or modify the same version, Git may report conflicting changes.

Review both versions and preserve the dependencies required by the application. Check for duplicate keys, incompatible version ranges, and changes to scripts.

Conflicts in package-lock.json, yarn.lock, and pnpm-lock.yaml

These lockfiles record resolved dependency versions and related metadata. Avoid manually combining arbitrary lockfile sections unless you understand their format and dependency relationships.

A practical workflow is to resolve package.json first, regenerate or update the appropriate lockfile using the project’s package manager, and inspect the resulting changes.

For example, an npm project may use:

npm install
npm test
npm run build

The correct commands depend on the project, its package manager, and its dependency configuration. Do not replace a project’s established package-management workflow with commands intended for another tool.

Git Merge Conflict Best Practices

Following merge conflict best practices reduces the likelihood of errors and makes collaboration more predictable.

Prevent Merge Conflicts Before They Happen

To prevent merge conflicts, keep feature branches reasonably short-lived, integrate changes regularly, communicate about shared files, and avoid unnecessary overlapping modifications.

Developers should also write focused commits and keep unrelated changes separate. Smaller, understandable changes are generally easier to review and resolve than large, mixed-purpose commits.

Avoid Conflicts When Working in Teams

Teams can avoid many conflicts by establishing clear ownership of critical files, discussing major refactors, and coordinating changes to shared configuration files.

Use feature branches and pull requests to isolate development work. Code reviews help identify incompatible assumptions before changes enter the main branch.

Establish a Consistent Git Branching Strategy

A Git branching strategy defines how developers create, update, review, and merge branches.

Common approaches include short-lived feature branches, release branches, and trunk-based development. The right strategy depends on team size, release requirements, deployment practices, and the complexity of the application.

Whichever approach you choose, document the expected merge or rebase process so contributors know how to resolve conflicts consistently.

Use Continuous Integration

Continuous integration runs automated checks when developers push changes or open pull requests. Tests, linting, type checking, and builds help identify problems introduced during conflict resolution.

CI cannot eliminate every merge conflict, but it can catch many integration problems before changes reach production.

Resolve Conflicts Without Losing Code

Before starting a complicated merge, commit or back up important work. Read the conflict markers, compare the original versions, and understand the purpose of each change before editing.

Avoid blindly accepting the current or incoming version across every file. A single command that resolves one file correctly may discard important work in another.

After resolution, inspect the staged changes using:

git diff --cached

This helps you review exactly what is about to be included in the next commit.

Git Merge Conflict vs. Rebase Conflict

A Git merge conflict and a Git rebase conflict are related, but they occur during different operations.

A merge is often suitable when a team wants to preserve the explicit history of integrating branches. A rebase is useful when a team prefers a more linear history, but it changes commit identities and requires care when working with shared branches.

Neither approach eliminates the need to understand conflicting changes.

Git Merge Conflict vs. Fast-Forward Merge

A fast-forward merge occurs when the current branch can move forward to a later commit without creating a separate merge commit. This is possible when the current branch has not diverged from the branch being integrated.

A traditional merge can combine diverged histories and may create a merge commit. If overlapping changes cannot be combined automatically, a merge conflict may occur.

The important distinction is that a fast-forward merge describes how Git updates branch history, while a merge conflict describes a situation where Git cannot automatically reconcile changes.

Common Git Errors and Solutions

Beginner Git troubleshooting becomes easier when you distinguish merge conflicts from other repository problems.

Error: Automatic merge failed.

Git could not complete the merge automatically. Run git status, inspect the affected files, resolve the conflicts, stage the files, and complete the merge.

Error: Unmerged paths.

One or more files still contain unresolved conflicts. Inspect each path, remove the conflict markers through a valid resolution, and stage the resulting files.

Error: Git push rejected.

The remote branch may contain commits missing from your local branch. Fetch the updates and integrate them using the team’s preferred strategy before trying again.

Error: Conflicts appear after pulling.

A Git pull conflict usually indicates that local and remote changes overlap. Inspect the repository state and resolve the conflicts instead of repeatedly pulling without addressing them.

Error: A file still contains conflict markers.

Search the relevant files for <<<<<<<, =======, and >>>>>>>. Remove the markers from the final source and verify that the intended code remains.

Error: The application fails after the merge.

A conflict can be resolved syntactically but incorrectly from a business-logic perspective. Review the changes, run tests, inspect application logs, and restore missing functionality as necessary.

If your investigation involves branch history or an unusual repository state, understanding Git detached HEAD can also help you diagnose situations in which HEAD points directly to a commit rather than a branch.

How AI Coding Assistants Can Help Resolve Git Merge Conflicts

AI coding assistants can explain, detect, and help resolve Git merge conflicts by analyzing conflict markers, comparing code sections, suggesting combined implementations, and identifying possible logical inconsistencies.

For example, an AI assistant may help explain why two functions conflict, suggest a resolution that preserves both sets of requirements, or recommend tests for a modified component.

However, AI-generated resolutions must be reviewed carefully. An assistant may not know the full project architecture, runtime assumptions, security requirements, or intended business logic. It can also suggest code that compiles but produces incorrect results.

For better results, provide the relevant source files, explain what each branch was intended to accomplish, describe the expected behavior, and run the project’s automated tests after applying the suggested resolution.

AI can accelerate the review process, but developers remain responsible for verifying that the final code is correct and maintainable.

Frequently Asked Questions About Git Merge Conflicts

Conclusion

A Git merge conflict is a normal part of version control when Git cannot automatically combine changes from different branches. By learning the causes of conflicts, recognizing conflict markers, using commands such as git status, git diff, git add, and git merge --abort, and following a consistent resolution process, developers can integrate changes safely and efficiently.

The most reliable Git conflict resolution workflow involves inspecting both versions, understanding the intended behavior, editing the conflicting files, staging the results, completing the pending operation, and testing the application. Tools such as VS Code, IntelliJ IDEA, GitHub, GitLab, Bitbucket, and AI coding assistants can simplify the process, but careful review remains essential.

For long-term success, adopt a consistent Git branching strategy, keep branches manageable, communicate with teammates, review code changes, and use continuous integration to detect problems early. These practices help prevent unnecessary conflicts and make collaborative software development more predictable.

Continue learning Git through practical tutorials on CCodeLearner to strengthen your version control skills and become more confident when managing branches, commits, and collaborative development workflows.