johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Complete import.orphan_handling documentation (bd-9cdc)

Browse Source 
Added comprehensive documentation for import orphan handling configuration
across all relevant documentation files:

- AGENTS.md: Added "Import Configuration" section with detailed mode
  explanations and usage guidance
- README.md: Documented orphan handling in Export/Import section with
  examples of all four modes
- TROUBLESHOOTING.md: Added "Import fails with missing parent errors"
  troubleshooting section with resurrection examples and prevention tips
- CLI_REFERENCE.md: Expanded Import/Export section with --orphan-handling
  flag documentation and cross-references

Documented resurrection behavior:
- Tombstone creation (Status=Closed, Priority=4)
- JSONL history search for deleted parents
- Best-effort dependency resurrection
- Hierarchical ancestor chain handling

Closes bd-9cdc

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-11-24 01:07:50 -08:00
parent 5d11cf1842
commit e0e6dff87f
5 changed files with 160 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/CLI_REFERENCE.md
View File

@@ -341,14 +341,32 @@ bd import -i .beads/issues.jsonl --dry-run # Preview changes
bd import -i .beads/issues.jsonl # Import and update issues
bd import -i .beads/issues.jsonl --dedupe-after # Import + detect duplicates
# Note: Import automatically handles missing parents!
# - If a hierarchical child's parent is missing (e.g., bd-abc.1 but no bd-abc)
# - bd will search the JSONL history for the parent
# - If found, creates a tombstone placeholder (Status=Closed, Priority=4)
# - Dependencies are also resurrected on best-effort basis
# - This prevents import failures after parent deletion
# Handle missing parents during import
bd import -i issues.jsonl --orphan-handling allow # Default: import orphans without validation
bd import -i issues.jsonl --orphan-handling resurrect # Auto-resurrect deleted parents as tombstones
bd import -i issues.jsonl --orphan-handling skip # Skip orphans with warning
bd import -i issues.jsonl --orphan-handling strict # Fail if parent is missing
# Configure default orphan handling behavior
bd config set import.orphan_handling "resurrect"
bd sync # Now uses resurrect mode by default
```
**Orphan handling modes:**
- **`allow` (default)** - Import orphaned children without parent validation. Most permissive, ensures no data loss even if hierarchy is temporarily broken.
- **`resurrect`** - Search JSONL history for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis.
- **`skip`** - Skip orphaned children with warning. Partial import succeeds but some issues are excluded.
- **`strict`** - Fail import immediately if a child's parent is missing. Use when database integrity is critical.
**When to use:**
- Use `allow` (default) for daily imports and auto-sync
- Use `resurrect` when importing from databases with deleted parents
- Use `strict` for controlled imports requiring guaranteed parent existence
- Use `skip` rarely - only for selective imports
See [CONFIG.md](CONFIG.md#example-import-orphan-handling) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md#import-fails-with-missing-parent-errors) for more details.
### Migration
```bash