Conflict Resolution Overview
Handle merge conflicts systematically to maintain code integrity.
Core principle: Conflicts require careful resolution, not just picking one side.
Announce at start: "I'm using conflict-resolution to handle these merge conflicts."
When Conflicts Occur
Conflicts happen when:
Situation Example Rebasing on updated main git rebase origin/main Merging main into branch git merge origin/main Cherry-picking commits git cherry-pick [sha] Pulling with local changes git pull The Resolution Process Conflict Detected │ ▼ ┌─────────────────┐ │ 1. UNDERSTAND │ ← What's conflicting and why? └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 2. ANALYZE │ ← Review both versions └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 3. RESOLVE │ ← Make informed decision └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 4. VERIFY │ ← Tests pass, code works └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 5. CONTINUE │ ← Complete the operation └─────────────────┘
Step 1: Understand the Conflict See Conflicting Files
List files with conflicts
git status
Output shows:
Unmerged paths:
both modified: src/services/user.ts
both modified: src/utils/validation.ts
View the Conflict
See the conflict markers
cat src/services/user.ts
<<<<<<< HEAD
// Your changes
function createUser(data: UserData): User {
return { ...data, id: generateId() };
}
=======
// Their changes (main branch)
function createUser(data: UserData): Promise
main
Understand the History
See what changed in each branch
git log --oneline --left-right HEAD...main -- src/services/user.ts
See the actual changes
git diff HEAD...main -- src/services/user.ts
Step 2: Analyze Both Versions Questions to Answer Question Consider What was the intent of your change? Your feature/fix What was the intent of their change? Their feature/fix Are they mutually exclusive? Can both coexist? Which is more recent/correct? Check issue references Do both need to be kept? Merge the logic Compare Approaches
Conflict Analysis: src/services/user.ts
My Change (feature/issue-123)
- Made createUser synchronous
- Reason: Simplified for local testing
- Issue: #123
Their Change (main)
- Made createUser async with DB
- Reason: Production database integration
- Issue: #456
Resolution
Keep their async version (production requirement). My testing simplification should use mocks instead.
Step 3: Resolve the Conflict Resolution Strategies Keep Theirs (Main)
When main's version is correct:
Use their version
git checkout --theirs src/services/user.ts git add src/services/user.ts
Keep Ours (Your Branch)
When your version is correct:
Use your version
git checkout --ours src/services/user.ts git add src/services/user.ts
Manual Merge (Both)
When both changes are needed:
// Remove conflict markers // Combine both changes intelligently
// Result: Keep async from main, add your new validation
async function createUser(data: UserData): Promise
// Their change: async DB call return db.create({ ...data, id: generateId() }); }
After editing
git add src/services/user.ts
Conflict Markers
Remove ALL conflict markers:
<<<<<<< HEAD ← Remove ======= ← Remove
main ← Remove
The final file should have NO conflict markers.
Step 4: Verify Resolution Syntax Check
TypeScript: Check types
pnpm typecheck
Or for specific file
npx tsc --noEmit src/services/user.ts
Run Tests
Run all tests
pnpm test
Run tests for affected area
pnpm test --grep "user"
Visual Review
See final resolved state
git diff --cached
Ensure no conflict markers remain
grep -r "<<<<<<" src/ grep -r "======" src/ grep -r ">>>>>>" src/
Step 5: Continue the Operation After Rebase
Continue the rebase
git rebase --continue
If more conflicts, repeat resolution
When complete:
git push --force-with-lease
After Merge
Complete the merge
git commit -m "Merge main into feature/issue-123"
Push
git push
Abort if Needed
If resolution goes wrong:
Abort rebase
git rebase --abort
Abort merge
git merge --abort
Start fresh
Complex Conflicts Multiple Files
Resolve one file at a time:
See all conflicts
git status
Resolve each
1. Edit file
2. git add file
3. Next file
When all resolved
git rebase --continue
Semantic Conflicts
Sometimes code merges cleanly but is semantically broken:
// main: Function signature changed function process(data: NewFormat): Result
// yours: Called with old format process(oldFormatData); // No conflict marker, but broken!
Always run tests after resolution.
Conflicting Dependencies // package.json conflict <<<<<<< HEAD "dependencies": { "library": "^2.0.0" ======= "dependencies": { "library": "^1.5.0"
main
Resolution:
Choose the appropriate version Delete pnpm-lock.yaml Run pnpm install Commit the new lock file Best Practices Before Resolution Pull latest main frequently to minimize conflicts Keep branches short-lived Communicate about shared files During Resolution Take your time Understand both changes Don't just pick "ours" or "theirs" blindly Test after resolution After Resolution Run full test suite Review the merged result Commit with clear message Conflict Message
When conflicts occur during PR:
Merge Conflict Resolution
This PR had conflicts with main that have been resolved.
Conflicting Files
src/services/user.tssrc/utils/validation.ts
Resolution Summary
user.ts: Kept async implementation from main, added validation from this PR.
validation.ts: Merged both validation rules (main added email, this PR added phone).
Verification
- [x] All tests pass
- [x] Build succeeds
- [x] No conflict markers in code
- [x] Functionality verified manually
Checklist
When resolving conflicts:
All conflicting files identified Each conflict analyzed (understood both sides) Resolution chosen (ours/theirs/merge) Conflict markers removed Files staged (git add) Tests pass Build succeeds No remaining conflict markers Operation completed (rebase --continue / commit) Integration
This skill is called when:
git rebase encounters conflicts git merge encounters conflicts PR shows conflicts
This skill ensures:
Clean resolution No lost changes Working code after merge