Systematic cleanup of stale documentation references left over from the Dolt migration: - Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files - Replace all 'bd import' → 'bd init --from-jsonl' or remove - Replace 'bd init --branch' → note about refs/dolt/data separation - Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly) - Fix npm-package, claude-plugin, integrations, examples, website docs Add scripts/check-doc-flags.sh to catch stale doc references: - Checks for removed commands (bd sync, bd import) - Checks for removed flags (bd init --branch) - Warns on legacy SQLite/beads.db references - Compares CLI_REFERENCE.md against bd help --all Add CI job (check-doc-flags) and Makefile target (check-docs) to gate PRs against doc freshness. Prior art: feat/help-doc-generator branch has bd help --doc/--list for generating docs FROM CLI output. This script validates docs AGAINST CLI output — complementary approaches. Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6 Co-authored-by: Amp <amp@ampcode.com>
2.6 KiB
2.6 KiB
| id | title | sidebar_position |
|---|---|---|
| hash-ids | Hash-based IDs | 5 |
Hash-based IDs
Understanding beads' collision-resistant ID system.
The Problem
Traditional sequential IDs (#1, #2, #3) break when:
- Multiple agents create issues simultaneously
- Different branches have independent numbering
- Forks diverge and later merge
The Solution
Beads uses hash-based IDs:
bd-a1b2c3 # Short hash
bd-f14c # Even shorter
bd-a3f8e9.1 # Hierarchical (child of bd-a3f8e9)
Properties:
- Globally unique (content-based hash)
- No coordination needed between creators
- Merge-friendly across branches
- Predictable length (configurable)
How Hashes Work
IDs are generated from:
- Issue title
- Creation timestamp
- Random salt
# Create issue - ID assigned automatically
bd create "Fix authentication bug"
# Returns: bd-7x2f
# The ID is deterministic for same content+timestamp
Hierarchical IDs
For epics and subtasks:
# Parent epic
bd create "Auth System" -t epic
# Returns: bd-a3f8e9
# Children auto-increment
bd create "Design UI" --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend" --parent bd-a3f8e9 # bd-a3f8e9.2
bd create "Tests" --parent bd-a3f8e9 # bd-a3f8e9.3
Benefits:
- Clear parent-child relationship
- No namespace collision (parent hash is unique)
- Up to 3 levels of nesting
ID Configuration
Configure ID prefix and length:
# Set prefix (default: bd)
bd config set id.prefix myproject
# Set hash length (default: 4)
bd config set id.hash_length 6
# New issues use new format
bd create "Test"
# Returns: myproject-a1b2c3
Collision Handling
While rare, collisions are handled automatically:
- On import, if hash collision detected
- Beads appends disambiguator
- Both issues preserved
# Check for collisions
bd info --schema --json | jq '.collision_count'
Working with IDs
# Partial ID matching
bd show a1b2 # Finds bd-a1b2...
bd show auth # Fuzzy match by title
# Full ID required for ambiguous cases
bd show bd-a1b2c3d4
# List with full IDs
bd list --full-ids
Migration from Sequential IDs
If migrating from a system with sequential IDs:
# Bootstrap from a JSONL export (preserves original IDs in metadata)
bd init --from-jsonl old-issues.jsonl
# View original ID
bd show bd-new --json | jq '.original_id'
Best Practices
- Use short references -
bd-a1b2is usually unique enough - Use
--jsonfor scripts - Parse full ID programmatically - Reference by hash in commits -
Fixed bd-a1b2in commit messages - Let hierarchies form naturally - Create epics, add children as needed