How to fix This branch has conflicts that must be resolved in Git

GitBEGINNERMEDIUMUpdated Dec 6, 2025· 303 views

This GitHub error appears when you try to merge a pull request but the source and target branches have conflicting changes. You must resolve the conflicts either through the GitHub web interface or by pulling the branches locally, fixing conflicts manually, and pushing the resolved code.

Quick fix

Fixes This branch has conflicts that must be resolved

# Fetch the latest changes
git fetch origin

# See what files would conflict
git checkout your-branch
git merge origin/main --no-commit --no-ff

# If conflicts exist, git will list them
# Then abort to try a different approach
git merge --abort
  1. Review which files have conflicts
  2. Resolve conflicts using GitHub's web editor (simple conflicts)
  3. Resolve conflicts locally by merging main into your branch
  4. Resolve conflicts locally by rebasing (cleaner history)
git — error
# Fetch the latest changes
git fetch origin
# See what files would conflict
git checkout your-branch
git merge origin/main --no-commit --no-ff
# If conflicts exist, git will list them
# Then abort to try a different approach
git merge --abort
This branch has conflicts that must be resolved

What this error means

This error appears in the GitHub pull request interface when Git cannot automatically merge your branch into the target branch (usually `main` or `master`). The merge button becomes disabled, and GitHub displays "This branch has conflicts that must be resolved" at the bottom of the PR page. The conflict occurs because both your branch and the target branch have modified the same lines of code (or nearby lines) since they diverged. Git's automatic merge algorithm cannot determine which changes should take precedence, so it requires human intervention. This is not an error with your code per se—it's a normal part of collaborative development. It simply means that while you were working on your feature branch, someone else merged changes to the same files you modified, and now those changes overlap in a way that Git cannot automatically reconcile.

Typical symptoms

  • GitHub merge button is grayed out or disabled
  • Message 'This branch has conflicts that must be resolved' appears on PR page
  • GitHub shows 'Conflicting files' section listing affected files
  • Cannot complete merge via GitHub UI without resolving conflicts
  • 'Resolve conflicts' button appears in GitHub PR interface
  • PR checks may show merge conflict status
  • Branch protection rules may block merge due to conflicts
  • GitHub Actions workflows cannot auto-merge the PR

Common causes

  1. Both your branch and target branch modified the same lines of a file
  2. Target branch received new commits after you created your feature branch
  3. Another PR was merged that changed files you also modified
  4. Long-lived feature branch that diverged significantly from main
  5. Rebasing or squashing commits on the target branch
  6. Multiple developers working on the same feature area simultaneously
  7. Auto-formatting or linting rules changed files you also modified
  8. Merge commits from other branches affecting shared code

How to fix "This branch has conflicts that must be resolved"

1Review which files have conflicts

First, identify the conflicting files on GitHub:

1. Navigate to your pull request on GitHub
2. Scroll to the bottom where you see "This branch has conflicts that must be resolved"
3. Click "Resolve conflicts" to see a list of conflicting files
4. Note which files need resolution

Alternatively, view conflicts from the command line:

bash
# Fetch the latest changes
git fetch origin

# See what files would conflict
git checkout your-branch
git merge origin/main --no-commit --no-ff

# If conflicts exist, git will list them
# Then abort to try a different approach
git merge --abort
2Resolve conflicts using GitHub's web editor (simple conflicts)

For simple conflicts, GitHub's web editor is quick and convenient:

1. On the PR page, click "Resolve conflicts"
2. GitHub opens a web editor showing the conflicted files
3. Look for conflict markers:

text
<<<<<<< your-branch
Your code changes here
=======
Code from main branch here
>>>>>>> main

4. Edit the file to keep the desired code:
 - Remove the conflict markers (<<<<<<<, =======, >>>>>>>)
 - Keep the code you want (your version, their version, or a combination)

5. Click "Mark as resolved" for each file
6. After all conflicts are resolved, click "Commit merge"

Limitations: GitHub's web editor doesn't work well for:
- Complex conflicts spanning many lines
- Binary files
- Files requiring code execution to verify correctness

3Resolve conflicts locally by merging main into your branch

For complex conflicts, resolve locally:

bash
# Make sure you're on your feature branch
git checkout your-feature-branch

# Fetch the latest changes from remote
git fetch origin

# Merge the target branch into your branch
git merge origin/main

Git will report which files have conflicts:

bash
Auto-merging src/app.js
CONFLICT (content): Merge conflict in src/app.js
Automatic merge failed; fix conflicts and then commit the result.

Now resolve each conflicted file:

bash
# Open the conflicted file in your editor
# Look for and resolve conflict markers
# Save the file

# Stage the resolved file
git add src/app.js

# After all conflicts are resolved, commit
git commit -m "Merge main into feature-branch, resolve conflicts"

# Push the resolved branch to GitHub
git push origin your-feature-branch

The PR will automatically update and the merge button will become available.

4Resolve conflicts locally by rebasing (cleaner history)

Rebasing creates a cleaner commit history by replaying your commits on top of main:

bash
# Make sure you're on your feature branch
git checkout your-feature-branch

# Fetch latest changes
git fetch origin

# Rebase your branch onto the target branch
git rebase origin/main

When conflicts occur during rebase:

bash
# Git will pause and show which files conflict
# Edit and fix each conflicted file
# Remove conflict markers and save

# Stage resolved files
git add src/app.js

# Continue the rebase
git rebase --continue

# If more conflicts occur, repeat the process
# If you want to abort and start over:
git rebase --abort

After successful rebase:

bash
# Force push (required because rebase rewrites history)
git push --force-with-lease origin your-feature-branch

Note: Only force push to feature branches, never to shared branches like main.

5Use a merge tool for complex conflicts

For files with many conflicts, use a visual merge tool:

bash
# Start the merge (if not already in progress)
git merge origin/main

# Launch the configured merge tool
git mergetool

Configure a merge tool:

bash
# VS Code
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

# IntelliJ/WebStorm
git config --global merge.tool intellij
git config --global mergetool.intellij.cmd 'idea merge $LOCAL $REMOTE $BASE $MERGED'

# Other options: meld, kdiff3, vimdiff

VS Code built-in merge editor:
VS Code highlights conflicts and provides inline buttons:
- "Accept Current Change" (your version)
- "Accept Incoming Change" (their version)
- "Accept Both Changes"
- "Compare Changes"

6Accept all changes from one side (when appropriate)

If you know you want to keep all changes from one branch:

During merge - keep your changes:

bash
git merge -X ours origin/main

During merge - keep their changes:

bash
git merge -X theirs origin/main

For specific files during conflict:

bash
# Keep your version of a specific file
git checkout --ours path/to/file.js
git add path/to/file.js

# Keep their version of a specific file
git checkout --theirs path/to/file.js
git add path/to/file.js

Warning: These commands discard changes from one side without review. Only use when you're certain which version is correct—typically when one side's changes are completely obsolete.

7Verify the resolution and run tests

After resolving conflicts, verify your code still works:

bash
# Check for any remaining conflict markers
grep -r "<<<<<<" . --include="*.js" --include="*.ts" --include="*.py"
grep -r "=======" . --include="*.js" --include="*.ts" --include="*.py"
grep -r ">>>>>>" . --include="*.js" --include="*.ts" --include="*.py"

# Run your test suite
npm test
# or
pytest
# or
go test ./...

# Build the project to check for compilation errors
npm run build

Before pushing:
- Review the changes: git diff origin/main
- Make sure tests pass
- Run linting: npm run lint
- Verify the app runs correctly locally

8Update the pull request

After resolving conflicts locally, push your changes:

bash
# If you used merge
git push origin your-feature-branch

# If you used rebase (requires force push)
git push --force-with-lease origin your-feature-branch

On GitHub:
1. Return to your pull request page
2. GitHub will detect the new commits
3. The conflict warning should disappear
4. The merge button should become available
5. Wait for CI checks to pass
6. Merge the PR

If conflicts reappear:
This can happen if someone else merged to main while you were resolving. Simply repeat the process:

bash
git fetch origin
git merge origin/main  # or git rebase origin/main
# Resolve any new conflicts
git push origin your-feature-branch

Advanced notes

### Understanding Conflict Frequency

Conflicts are more common in certain scenarios:
- Hot files: Configuration files, package.json, styles
- Large teams: More parallel changes to the same codebase
- Long-lived branches: More time for main to diverge
- Monorepos: More developers touching shared code

### Prevention Strategies

Keep branches short-lived:
- Merge or rebase frequently (daily if possible)
- Break large features into smaller PRs
- Use feature flags to merge incomplete features

Communicate with your team:
- Announce when you're working on shared files
- Coordinate on major refactoring efforts
- Use CODEOWNERS to track file ownership

Fetch and integrate often:

bash
# Daily routine
git fetch origin
git rebase origin/main  # or merge

### GitHub's Merge Options

GitHub offers three merge methods with different conflict implications:

| Method | Command | History | Conflicts |
|--------|---------|---------|-----------|
| Merge commit | git merge | Preserves all commits | One resolution |
| Squash and merge | git merge --squash | Single commit | One resolution |
| Rebase and merge | git rebase | Linear history | Per-commit resolution |

### Branch Protection and Conflicts

If your repo has branch protection rules:
- PRs with conflicts cannot be merged even by admins
- Required status checks won't run until conflicts are resolved
- Some teams require branches to be up-to-date before merging

Enable "Require branches to be up to date before merging" to reduce conflicts:

bash
Repository Settings > Branches > Branch protection rules
☑ Require branches to be up to date before merging

### Auto-merge Feature

GitHub's auto-merge waits for all requirements to pass, then merges automatically. However, if conflicts appear before merge, auto-merge is paused:

bash
# Enable auto-merge on a PR (via GitHub CLI)
gh pr merge --auto --merge

### Conflict Resolution in CI/CD

Some teams automate conflict detection:

yaml
# GitHub Actions - Check for merge conflicts
name: Conflict Check
on: pull_request

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Check for conflicts
        run: |
          git fetch origin main
          git merge origin/main --no-commit --no-ff || exit 1

### Rerere: Remember Resolutions

Git can remember how you resolved specific conflicts:

bash
git config --global rerere.enabled true

Next time you encounter the same conflict pattern, Git applies your previous resolution automatically.

### Binary File Conflicts

Binary files (images, PDFs, compiled assets) can't be merged textually:

bash
# Keep your version
git checkout --ours path/to/image.png

# Keep their version
git checkout --theirs path/to/image.png

git add path/to/image.png

### Getting Help

If you're stuck on a complex conflict:
1. Ask the author of the conflicting changes for context
2. Use git log --oneline --graph to understand branch history
3. Consider checking out a fresh branch and cherry-picking commits

Frequently asked questions

What does "This branch has conflicts that must be resolved" mean?
This error appears in the GitHub pull request interface when Git cannot automatically merge your branch into the target branch (usually main or master). The merge button becomes disabled, and GitHub displays "This branch has conflicts that must be resolved" at the bottom of the PR page. The conflict occurs because both your branch and the target branch have modified the same lines of code (or nearby lines) since they diverged.
How do I fix "This branch has conflicts that must be resolved"?
This GitHub error appears when you try to merge a pull request but the source and target branches have conflicting changes. You must resolve the conflicts either through the GitHub web interface or by pulling the branches locally, fixing conflicts manually, and pushing the resolved code.
What causes "This branch has conflicts that must be resolved"?
Both your branch and target branch modified the same lines of a file Target branch received new commits after you created your feature branch Another PR was merged that changed files you also modified
Is the "This branch has conflicts that must be resolved" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading