Video 22.3: Merge Strategies and Conflict Resolution

Course: Claude Code - Parallel Agent Development (Course 4) Section: S22 - Git Worktrees and Manual Patterns Video Length: 4-5 minutes Presenter: Daniel Treasure

Opening Hook

Two agents working in parallel sounds great until they modify the same file. Now you've got a merge conflict. In this video, we'll explore how to prevent conflicts in the first place, how to detect them early, and how to resolve them when they happen. The goal is simple: ship faster without chaos.

Key Talking Points

What to Say: Conflict Prevention Strategy

Prevention is easier than resolution: The best merge conflict is one that never happens. Design your task split so agents modify completely different files.
File-level ownership: The strongest pattern is file-level isolation. "Agent A, you own services/auth.ts and services/user.ts. Agent B, you own schema/users.sql and schema/roles.sql." If files don't overlap, conflicts can't happen.
Directories as boundaries: Assign agents by directory. One agent modifies src/services/, the other modifies src/schema/. As long as they don't share files in subdirectories, they're safe.
Early detection with clash: If you're worried about overlap, the clash tool scans all worktrees after each commit and warns you of potential conflicts before you merge. It's like a safety net.
Simple lock mechanism: For truly shared files (like package.json or config), use a simple task file: write to current_tasks/ or a .lock file. First agent to write the lock owns that file.

What to Say: Resolution When Conflicts Happen

Standard Git merge applies: When you're ready to merge, use git merge as normal. If conflicts exist, they'll show up in the merge conflict format.
Conflicted files show both versions: Git marks the conflicting sections with <<<<<<<, =======, and >>>>>>>. You (or Claude) can then choose which version to keep or combine them intelligently.
Incremental merging: You don't have to merge everything at once. Merge completed worktrees first, verify they work, then handle the next one. Reduces risk.
Who does the merge?: You can merge manually (editing files yourself), ask Claude to help resolve conflicts, or use Git merge tools. Each approach has trade-offs.

What to Show on Screen: Clash and Conflict Detection

Show clash tool scanning worktrees (or simulating the scan)
Demonstrate how it identifies potential conflicts before merge
Show a commit in one worktree that might conflict with another
Manually create a conflict (intentionally modify the same line in two worktrees)
Show the conflict in Git after merge attempt
Resolve it using either manual editing or Claude's help
Show the clean state after resolution
Demonstrate merging a clean worktree (no conflicts) and fast-forward merge

Demo Plan

Timing: ~2.5-3 minutes for demo

Step 1: Set Up Test Worktrees with Conflicting Potential (1 minute)

Verify you have 2-3 worktrees running: git worktree list
In worktree A, modify a shared file (e.g., src/config.ts):
Add a line: export const API_URL = "http://localhost:3000";
Commit: git add . && git commit -m "Add API_URL to config"
In worktree B, modify the same file differently:
Add a different line: export const API_SECRET = "secret123";
Commit: git add . && git commit -m "Add API_SECRET to config"
Show both commits exist in the log

Step 2: Demonstrate Clash Tool (Optional / 45 seconds)

If clash is installed, run it to scan worktrees:
clash scan or clash check (exact command depends on installation)
Show the output warning about potential conflicts
If clash isn't installed, skip to Step 3 and mention that this is what clash would catch automatically

Step 3: Attempt Merge and Show Conflict (1 minute)

Go to the main worktree (main branch): cd ../main or similar
Try to merge both feature branches:
git merge auth-worktree (assuming it's a branch name)
This should succeed (no conflict yet)
Try to merge the second worktree:
git merge database-worktree
This should show a merge conflict (both modified src/config.ts)
Show the conflict output: Git marks the conflicting sections
Run: git status to show the conflicted file

Step 4: Inspect the Conflicted File (45 seconds)

Open the conflicted file: cat src/config.ts (or use editor)
Show the conflict markers: ``` <<<<<<< HEAD export const API_URL = "http://localhost:3000"; ======= export const API_SECRET = "secret123";

database-worktree ```
Explain what each section means: HEAD is the current branch, the other section is what's being merged in
Show how you'd resolve it: keep both lines (they're not actually conflicting in logic, just in location)

Step 5: Resolve the Conflict (45 seconds)

Edit the file to remove conflict markers and keep both lines: typescript export const API_URL = "http://localhost:3000"; export const API_SECRET = "secret123";
Save the file
Mark as resolved: git add src/config.ts
Complete the merge: git commit -m "Merge database-worktree, resolved config.ts conflict"
Run: git status to show the repo is clean again

Step 6: Show a Clean Merge (No Conflicts) (30 seconds)

In a different worktree, create a new file and commit it: echo "test" > src/utils.ts && git add . && git commit -m "Add utils"
Go back to main and merge this one: git merge clean-branch-name
Show it merges with no conflicts (fast-forward or clean merge)
Point out: when agents own different files, merges are fast and clean

Code Examples & Commands

Preventing Conflicts: File Ownership

# Clear task assignment (in conversation with Claude, or in a comment):
# Agent A:
# - services/auth.ts
# - services/user.ts
# - tests/auth.test.ts

# Agent B:
# - schema/users.sql
# - schema/roles.sql
# - migrations/001_create_users.sql

Using Clash for Early Detection

# Install clash (if not already installed)
# Instructions vary by platform; check clash-sh documentation

# Scan worktrees for potential conflicts
clash scan

# Check a specific worktree against main
clash check --base main --worktree ../auth-worktree

# Get detailed conflict prediction
clash report

Handling Merge Conflicts

# Attempt to merge a worktree
git merge feature-branch-name

# If conflict occurs, see which files are conflicted
git status

# View the conflicted file with markers
cat src/config.ts
# or use an editor
code src/config.ts

# After resolving conflicts manually, mark as resolved
git add src/config.ts

# Complete the merge
git commit -m "Merge feature-branch-name, resolved conflicts"

# If you want to abort the merge entirely
git merge --abort

Merge Resolution Options

# View conflict with more context
git diff --ours          # Show your version
git diff --theirs       # Show their version
git diff --ours --theirs # Show both

# Keep your version entirely
git checkout --ours src/config.ts
git add src/config.ts

# Keep their version entirely
git checkout --theirs src/config.ts
git add src/config.ts

# Use a merge tool (if configured)
git mergetool

Incremental Merging

# Merge worktrees one at a time
git merge auth-worktree
# Test and verify
git merge database-worktree
# Test and verify
git merge payments-worktree
# Final test

# Each merge is isolated and testable

Lock File Pattern for Shared Resources

# In a shared file (e.g., package.json), use a comment convention:
# /* LOCKED BY: auth-worktree */

# Or create an actual lock file:
mkdir -p current_tasks
echo "agent-auth" > current_tasks/package.json.lock

# Other agents check before modifying:
cat current_tasks/package.json.lock
# If locked, they don't edit that file, or request the lock holder merge first

Gotchas & Tips

Common Pitfalls

Assuming fast-forward merges: Not all merges are fast-forward. Some create merge commits. Don't assume; check git log after merge.
Forgetting to push worktree branches: Each worktree is local until you push. If you lose the worktree directory before pushing, you lose the work. Push regularly.
Conflict markers in production: If you resolve conflicts but accidentally commit the conflict markers (the <<<<<<< lines), your code breaks. Always verify the file is clean after resolution.
Multiple conflicts in the same file: If the same file is modified in 3+ worktrees, the merge can be complex. Try to avoid this through good task design.

Pro Tips

Use meaningful branch names: feature/auth-system is clearer than feature/1. When conflicts occur, the branch name shows in the conflict marker, so be clear.
Merge frequently: Don't let worktrees diverge for too long. Merge small chunks of work regularly. Smaller merges = fewer conflicts.
Communicate out of band: If Agent A realizes they need to modify a file Agent B is working on, tell Agent B. Don't silently create conflicts.
Use Git GUIs for complex conflicts: For visual merge tools, use git mergetool or a GUI like GitHub Desktop, VS Code merge view, or Sublime Merge.
Automate tests after merge: After merging, run your tests immediately. Conflicts might be resolved but logic might be broken. CI/CD catches this.

Clash Tool Tips

Run it regularly: Not just before merge. Run it every commit cycle to catch conflicts early.
Fine-tune sensitivity: Some conflict detectors are too aggressive (warn on unrelated changes). Check clash config to tune it to your codebase.
Combine with code review: Clash finds mechanical conflicts; code review finds logical conflicts. Use both.

Lead-out

We've now covered the manual pattern: worktrees, parallel sessions, and conflict resolution. But if you're doing this at scale — 10+ agents, complex projects — managing everything manually gets tedious. That's where community tools come in. In the next video, we'll explore automated orchestration tools like agentree, ccswarm, and Crystal that handle worktree setup, task assignment, and merging for you.

Reference URLs

Git Merge Documentation
Git Conflict Resolution Guide
Clash Tool GitHub (if available; adjust based on actual repo)
Merge Strategy Patterns

Prep Reading

Review Git merge conflict documentation (5 min focus on conflict markers and resolution)
Set up test worktrees with intentional conflicting changes (30 min prep)
If using clash, install and test it beforehand (10 min)
Practice the merge demo at least once so it flows smoothly

Notes for Daniel

This video is about showing that conflicts, while intimidating, are manageable. The key is preventing them through good design. The demo should feel controlled and clear.

When showing conflict markers, make them visible and explain each section slowly. Viewers might never have resolved a conflict, so be explicit: "This part is from our current branch, this part is from the branch we're merging. We decide which to keep."

The resolution should feel straightforward. Don't make it seem scary. In most cases, you're just removing the markers and keeping both pieces of code. Show the before (with markers) and after (clean file) clearly.

If using clash, make sure it works beforehand. If it doesn't, you can still show the concept: "This is what clash would have caught automatically. Here's the warning it would have given us."

The incremental merge strategy is powerful: show that you can merge one worktree, test, then merge the next. It's safer than merging everything at once. Emphasize this for viewers doing actual production work.

Optional: Show a simple visual of the merge process: two worktree branches converging into main. Makes it easy to understand what's happening conceptually.

Quick Reference