Merge Conflicts Recovery

This runbook helps you resolve JSONL merge conflicts that occur during Git operations.

Symptoms

• Git merge conflicts in .beads/*.jsonl files
• bd sync fails with conflict errors
• Different issue states between clones

Diagnosis

# Check for conflicted files
git status

# Look for conflict markers
grep -l "<<<<<<" .beads/*.jsonl

Solution

warning

JSONL files are append-only logs. Manual editing requires care.

Step 1: Identify conflicted files

git diff --name-only --diff-filter=U

Step 2: For each conflicted JSONL file, keep both versions

# Accept both changes (append-only is safe)
git checkout --ours .beads/issues.jsonl
git add .beads/issues.jsonl

Step 3: Force rebuild to reconcile

bd doctor --fix

Step 4: Verify state

bd list
bd status

Step 5: Complete the merge

git commit -m "Resolved beads merge conflicts"

Prevention

• Sync before and after Git operations
• Use bd sync regularly
• Avoid concurrent modifications from multiple clones