beads/examples/branch-merge/README.md

Branch Merge Workflow with Collision Resolution

This example demonstrates how to handle ID collisions when merging branches that have diverged and created issues with the same IDs.

The Problem

When two branches work independently and both create issues, they'll often generate overlapping IDs:

main:    bd-1, bd-2, bd-3, bd-4, bd-5
feature: bd-1, bd-2, bd-3, bd-6, bd-7  (diverged from main earlier)

When you try to merge feature into main, you'll have ID collisions for bd-1 through bd-3 (if the content differs).

The Solution

bd provides automatic collision resolution that:

1. Detects collisions (same ID, different content)
2. Renumbers the incoming colliding issues
3. Updates ALL text references and dependencies automatically

Demo Workflow

1. Setup - Two Diverged Branches

# Start on main branch
git checkout main
bd create "Feature A" -t feature -p 1
bd create "Bug fix B" -t bug -p 0
bd create "Task C" -t task -p 2
bd export -o .beads/issues.jsonl
git add .beads/issues.jsonl
git commit -m "Add main branch issues"

# Create feature branch from an earlier commit
git checkout -b feature-branch HEAD~5

# On feature branch, create overlapping issues
bd create "Different feature A" -t feature -p 2
bd create "Different bug B" -t bug -p 1
bd create "Feature D" -t feature -p 1
bd export -o .beads/issues.jsonl
git add .beads/issues.jsonl
git commit -m "Add feature branch issues"

At this point:

• main has: bd-1 (Feature A), bd-2 (Bug fix B), bd-3 (Task C)
• feature-branch has: bd-1 (Different feature A), bd-2 (Different bug B), bd-3 (Feature D)

The bd-1 and bd-2 on each branch have different content = collisions!

2. Merge and Detect Collisions

# Merge feature branch into main
git checkout main
git merge feature-branch

# Git will show merge conflict in .beads/issues.jsonl
# Manually resolve the conflict by keeping both versions
# (or use a merge tool)

# After resolving the git conflict, check for ID collisions
bd import -i .beads/issues.jsonl --dry-run

Output shows:

=== Collision Detection Report ===
Exact matches (idempotent): 0
New issues: 1
COLLISIONS DETECTED: 2

Colliding issues:
  bd-1: Different feature A
    Conflicting fields: [title, priority]
  bd-2: Different bug B
    Conflicting fields: [title, priority]

3. Resolve Collisions Automatically

# Let bd resolve the collisions
bd import -i .beads/issues.jsonl --resolve-collisions

Output shows:

Resolving collisions...

=== Remapping Report ===
Issues remapped: 2

Remappings (sorted by reference count):
  bd-1 → bd-4 (refs: 0)
  bd-2 → bd-5 (refs: 0)

All text and dependency references have been updated.

Import complete: 2 created, 0 updated, 1 dependencies added, 2 issues remapped

Result:

• main keeps: bd-1 (Feature A), bd-2 (Bug fix B), bd-3 (Task C)
• feature-branch issues become: bd-4 (Different feature A), bd-5 (Different bug B), bd-3 (Feature D)

4. Export and Commit

# Export the resolved state back to JSONL
bd export -o .beads/issues.jsonl

# Commit the merge
git add .beads/issues.jsonl
git commit -m "Merge feature-branch with collision resolution"

Advanced: Cross-References

If your issues reference each other in text or dependencies, bd updates those automatically:

# On feature branch, create issues with references
bd create "Feature X" -d "Implements the core logic" -t feature -p 1
# Assume this becomes bd-10

bd create "Test for X" -d "Tests bd-10 functionality" -t task -p 2
# This references bd-10 in the description

bd dep add bd-11 bd-10 --type blocks
# Dependencies are created

# After merge with collision resolution
bd import -i .beads/issues.jsonl --resolve-collisions

# If bd-10 collided and was remapped to bd-15:
# - bd-11's description becomes: "Tests bd-15 functionality"
# - Dependency becomes: bd-11 → bd-15

When to Use This

1. Feature branches - Long-lived branches that create issues independently
2. Parallel development - Multiple developers working on separate branches
3. Stale branches - Old branches that need to be merged but have ID conflicts
4. Distributed teams - Teams that work offline and sync via git

Safety Notes

• --resolve-collisions preserves your existing database (current branch's issues never change IDs)
• Only the incoming colliding issues get new IDs
• Use --dry-run first to preview what will happen
• All text references use word-boundary matching (bd-10 won't match bd-100)
• The collision resolution is deterministic (same input = same output)

Alternative: Manual Resolution

If you prefer manual control:

1. Don't use --resolve-collisions
2. Manually edit the JSONL file before import
3. Rename colliding IDs to unique values
4. Manually update any cross-references
5. Import normally

This gives you complete control but is more error-prone and time-consuming.

See Also

• Git Hooks Example - Automate export/import with git hooks
• README.md - Full collision resolution documentation
• TEXT_FORMATS.md - JSONL merge strategies