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

18
README.md
View File

@@ -663,10 +663,28 @@ bd export -o issues.jsonl
# Import from JSONL (automatic when JSONL is newer)
bd import -i issues.jsonl
# Handle missing parents during import
bd import -i issues.jsonl --orphan-handling resurrect # Auto-recreate deleted parents
bd import -i issues.jsonl --orphan-handling skip # Skip orphans with warning
bd import -i issues.jsonl --orphan-handling strict # Fail on missing parents
# Manual sync
bd sync
```
**Import Orphan Handling:**
When importing hierarchical issues (e.g., `bd-abc.1`, `bd-abc.2`), bd needs to handle cases where the parent (`bd-abc`) has been deleted:
- **`allow` (default)** - Import orphans without validation. Most permissive, ensures no data loss.
- **`resurrect`** - Search JSONL history for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy.
- **`skip`** - Skip orphaned children with warning. Partial import.
- **`strict`** - Fail import if parent is missing.
Configure default behavior: `bd config set import.orphan_handling resurrect`
See [docs/CONFIG.md](docs/CONFIG.md) for complete configuration documentation.
**Note:** Auto-sync is enabled by default. Manual export/import is rarely needed.
### Managing Daemons