How Claude Code Resolves Git Merge Conflicts
The Problem
You pull from remote or merge a feature branch and Git dumps conflict markers throughout your files:
<<<<<<< HEAD
const API_URL = "https://api.production.com/v2";
=======
const API_URL = process.env.API_URL || "https://api.staging.com/v1";
>>>>>>> feature/config-refactor
Manually resolving dozens of conflicts across multiple files is tedious and error-prone. You need to understand both sides of each conflict, determine the correct resolution, and verify nothing breaks afterward.
Quick Fix
After a merge produces conflicts, ask Claude Code to resolve them:
I just merged origin/main into my feature branch and got conflicts.
Review each conflict, understand both sides, and resolve them.
Keep the intent of my feature branch while incorporating main's updates.
Claude Code reads the conflicted files, understands the context of both changes, and produces clean resolutions.
What’s Happening
When Git cannot automatically merge two branches, it marks the conflicting sections with <<<<<<<, =======, and >>>>>>> markers. Each conflict requires understanding what both sides intended and producing a version that preserves both goals.
Claude Code excels at this because it can:
- Read the full file context around each conflict, not just the marked lines
- Check git log to understand the purpose of each change
- Analyze related files that might be affected by the resolution
- Run tests after resolving to verify correctness
Step-by-Step Workflow
Step 1: Identify all conflicts
After a failed merge, list every conflicted file:
git diff --name-only --diff-filter=U
Or ask Claude Code directly:
Show me all files with merge conflicts and summarize what each conflict is about.
Claude Code will run git diff --name-only --diff-filter=U, read each conflicted file, and provide a summary like:
Found 4 files with conflicts:
1. src/config/database.ts - Connection pool settings (yours: pgBouncer, theirs: direct)
2. src/api/routes.ts - New endpoint added on both branches
3. package.json - Different versions of express dependency
4. src/utils/auth.ts - Token refresh logic rewritten on both sides
Step 2: Provide context for resolution
Give Claude Code the information it needs to make good decisions:
Resolve these merge conflicts with these priorities:
- My branch (feature/auth-v2) rewrites the auth system — prefer my auth changes
- Main branch updated database config for production — keep their DB changes
- For package.json, use the higher version of any shared dependency
- Run tests after resolving
Step 3: Let Claude Code resolve each conflict
Claude Code reads both sides of each conflict, checks the commit history for context, and produces a resolution. For example, a config conflict might resolve like this:
// Before (conflicted)
<<<<<<< HEAD
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
max: 20,
idleTimeoutMillis: 30000,
});
=======
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
max: 10,
ssl: { rejectUnauthorized: false },
});
>>>>>>> main
// After (resolved)
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
max: 20,
idleTimeoutMillis: 30000,
ssl: { rejectUnauthorized: false },
});
Claude Code recognized that HEAD increased the pool size while main added SSL configuration, and combined both changes.
Step 4: Handle complex conflicts
For files where both branches made significant changes to the same code, Claude Code can compare the intent rather than the text:
Both branches rewrote the auth middleware. My branch adds JWT refresh tokens.
Main branch adds rate limiting. Merge the functionality from both into a
single clean implementation.
Claude Code will read both versions, understand the separate features, and write a combined implementation that includes both JWT refresh and rate limiting.
Step 5: Verify the resolution
After resolving all conflicts, ask Claude Code to verify:
Run the test suite and check that the resolved merge doesn't break anything.
Also check for any remaining conflict markers in the codebase.
# Claude Code will run something like:
grep -r "<<<<<<< " src/
npm test
Step 6: Complete the merge
Once all conflicts are resolved and tests pass:
git add .
git commit -m "Merge main into feature/auth-v2: resolve conflicts in DB config, routes, deps, and auth"
Handling Package.json Conflicts
Package.json conflicts are extremely common and follow a predictable pattern. Ask Claude Code:
Resolve the package.json conflict by:
- Taking the higher version of any dependency present in both sides
- Including dependencies that are only on one side
- Keeping my scripts section but adding any new scripts from main
Claude Code handles the JSON structure correctly, ensuring no syntax errors in the merged result.
Prevention
Reduce merge conflicts by rebasing frequently:
# Instead of long-lived feature branches
git fetch origin
git rebase origin/main
Ask Claude Code to set up a pre-merge check:
Create a git hook that warns me if my branch is more than 10 commits
behind main, reminding me to rebase.
Keep files focused on single responsibilities. Large files that many branches modify are conflict magnets. If Claude Code notices a file causing repeated conflicts, ask it to split the file into smaller, more focused modules.