* docs: fix broken xref to docs/EXTENDING.md in extension example The extension example README referenced docs/EXTENDING.md in three places, but that file was deliberately deleted in the SQLite -> Dolt migration (see CHANGELOG entry "Deleted deprecated docs - removed EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer applicable)"). Anyone following the example hits a broken link. Removed all three references. The example README is itself the canonical reference for the extension pattern, so no redirect target is needed. Note: other docs in the repo still reference the deleted EXTENDING.md (docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md, website/docs/reference/advanced.md). Those are out of scope for this fix and should be addressed in follow-up issues. Tracking bead: mybd-q71 GH: #3683 PR: builds on follow-up audit from PR #3706 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: fix remaining broken xrefs to deleted EXTENDING.md across repo Round 1 (commitddeff314c) only fixed the extension example README because the original prompt scoped that PR narrowly. The bead (mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so this follow-up sweeps the rest in the same PR per the project's "one issue per PR" rule. Per-file treatment (EXTENDING.md was deleted in commit508387377before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has been broken since release): - docs/ADVANCED.md (3 refs): * Note in Extensible Database section: drop trailing "See EXTENDING.md for details" — the surrounding sentence about Dolt-era alternatives stands on its own. * Bold "See EXTENDING.md for complete documentation" line: redirect to the canonical working example (examples/bd-example-extension-go). * Next Steps bullet: same redirect. - docs/CONFIG.md (2 refs): * Namespace doc for compact_*: replace "(see EXTENDING.md)" with "(used by `bd admin compact`)" — the doc itself describes the keys, no external reference needed. * See Also bullet: replace with link to docs/ADVANCED.md (Extensible Database section). - examples/library-usage/README.md (1 ref): * See Also bullet: replace EXTENDING.md link with link to the sibling bd-example-extension-go example. - website/docs/reference/advanced.md (1 ref): * Custom Tables section: replace EXTENDING.md link with link to the bd-example-extension-go README on GitHub. - website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref): * Same fix as the live docs. EXTENDING.md was deleted before v1.0.0 release (commit508387377is an ancestor of tag v1.0.0), so this versioned snapshot has been broken since cut and a fix here doesn't violate frozen-in-time correctness — the link was never valid in the v1.0.0 release. - website/static/llms-full.txt (1 ref, auto-generated artifact): * Updated to match the corrected source so the on-disk artifact isn't broken until next regeneration. - beads.go and internal/beads/beads.go (package doc comments): * Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a pointer to examples/bd-example-extension-go. These were real broken pointers in published Go source comments. CHANGELOG.md historical entries left untouched (intentional history). cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG entry rendered by `bd info`, equivalent to a CHANGELOG line). Verification: grep -rn 'EXTENDING\.md' --include='*.md' . returns only CHANGELOG.md hits. Tracking bead: mybd-q71 GH: #3683 PR: #3713 (round 2) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: CI Bot <ci@beads.test> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
332 lines
11 KiB
Markdown
332 lines
11 KiB
Markdown
# Advanced bd Features
|
|
|
|
This guide covers advanced features for power users and specific use cases.
|
|
|
|
## Table of Contents
|
|
|
|
- [Renaming Prefix](#renaming-prefix)
|
|
- [Merging Duplicate Issues](#merging-duplicate-issues)
|
|
- [Git Worktrees](#git-worktrees)
|
|
- [Database Redirects](#database-redirects)
|
|
- [Handling Import Collisions](#handling-import-collisions)
|
|
- [Custom Git Hooks](#custom-git-hooks)
|
|
- [Extensible Database](#extensible-database)
|
|
- [Architecture: Storage, RPC, and MCP](#architecture-storage-rpc-and-mcp)
|
|
|
|
## Renaming Prefix
|
|
|
|
Change the issue prefix for all issues in your database. This is useful if your prefix is too long or you want to standardize naming.
|
|
|
|
```bash
|
|
# Preview changes without applying
|
|
bd rename-prefix kw- --dry-run
|
|
|
|
# Rename from current prefix to new prefix
|
|
bd rename-prefix kw-
|
|
|
|
# JSON output
|
|
bd rename-prefix kw- --json
|
|
```
|
|
|
|
The rename operation:
|
|
- Updates all issue IDs (e.g., `knowledge-work-1` → `kw-1`)
|
|
- Updates all text references in titles, descriptions, design notes, etc.
|
|
- Updates dependencies and labels
|
|
- Updates the counter table and config
|
|
|
|
**Prefix validation rules:**
|
|
- Max length: 8 characters
|
|
- Allowed characters: lowercase letters, numbers, hyphens
|
|
- Must start with a letter
|
|
- Must end with a hyphen (or will be trimmed to add one)
|
|
- Cannot be empty or just a hyphen
|
|
|
|
Example workflow:
|
|
```bash
|
|
# You have issues like knowledge-work-1, knowledge-work-2, etc.
|
|
bd list # Shows knowledge-work-* issues
|
|
|
|
# Preview the rename
|
|
bd rename-prefix kw- --dry-run
|
|
|
|
# Apply the rename
|
|
bd rename-prefix kw-
|
|
|
|
# Now you have kw-1, kw-2, etc.
|
|
bd list # Shows kw-* issues
|
|
```
|
|
|
|
## Duplicate Detection
|
|
|
|
Find issues with identical content using automated duplicate detection:
|
|
|
|
```bash
|
|
# Find all content duplicates in the database
|
|
bd duplicates
|
|
|
|
# Show duplicates in JSON format
|
|
bd duplicates --json
|
|
|
|
# Automatically merge all duplicates
|
|
bd duplicates --auto-merge
|
|
|
|
# Preview what would be merged
|
|
bd duplicates --dry-run
|
|
|
|
# Detect duplicates after initializing from JSONL
|
|
bd init --from-jsonl # then: bd duplicates
|
|
```
|
|
|
|
**How it works:**
|
|
- Groups issues by content hash (title, description, design, acceptance criteria)
|
|
- Only groups issues with matching status (open with open, closed with closed)
|
|
- Chooses merge target by reference count (most referenced) or smallest ID
|
|
- Reports duplicate groups with suggested merge commands
|
|
|
|
**Example output:**
|
|
|
|
```
|
|
🔍 Found 3 duplicate group(s):
|
|
|
|
━━ Group 1: Fix authentication bug
|
|
→ bd-10 (open, P1, 5 references)
|
|
bd-42 (open, P1, 0 references)
|
|
Suggested: bd merge bd-42 --into bd-10
|
|
|
|
💡 Run with --auto-merge to execute all suggested merges
|
|
```
|
|
|
|
**AI Agent Workflow:**
|
|
|
|
1. **Periodic scans**: Run `bd duplicates` to check for duplicates
|
|
2. **During import**: Use `--dedupe-after` to detect duplicates after collision resolution
|
|
3. **Auto-merge**: Use `--auto-merge` to automatically consolidate duplicates
|
|
4. **Manual review**: Use `--dry-run` to preview merges before executing
|
|
|
|
## Merging Duplicate Issues
|
|
|
|
Consolidate duplicate issues into a single issue while preserving dependencies and references:
|
|
|
|
```bash
|
|
# Merge bd-42 and bd-43 into bd-41
|
|
bd merge bd-42 bd-43 --into bd-41
|
|
|
|
# Merge multiple duplicates at once
|
|
bd merge bd-10 bd-11 bd-12 --into bd-10
|
|
|
|
# Preview merge without making changes
|
|
bd merge bd-42 bd-43 --into bd-41 --dry-run
|
|
|
|
# JSON output
|
|
bd merge bd-42 bd-43 --into bd-41 --json
|
|
```
|
|
|
|
**What the merge command does:**
|
|
1. **Validates** all issues exist and prevents self-merge
|
|
2. **Closes** source issues with reason `Merged into bd-X`
|
|
3. **Migrates** all dependencies from source issues to target
|
|
4. **Updates** text references across all issue descriptions, notes, design, and acceptance criteria
|
|
|
|
**Example workflow:**
|
|
|
|
```bash
|
|
# You discover bd-42 and bd-43 are duplicates of bd-41
|
|
bd show bd-41 bd-42 bd-43
|
|
|
|
# Preview the merge
|
|
bd merge bd-42 bd-43 --into bd-41 --dry-run
|
|
|
|
# Execute the merge
|
|
bd merge bd-42 bd-43 --into bd-41
|
|
# ✓ Merged 2 issue(s) into bd-41
|
|
|
|
# Verify the result
|
|
bd show bd-41 # Now has dependencies from bd-42 and bd-43
|
|
bd dep tree bd-41 # Shows unified dependency tree
|
|
```
|
|
|
|
**Important notes:**
|
|
- Source issues are permanently closed (status: `closed`)
|
|
- All dependencies pointing to source issues are redirected to target
|
|
- Text references like "see bd-42" are automatically rewritten to "see bd-41"
|
|
- Operation cannot be undone (but git history preserves the original state)
|
|
**AI Agent Workflow:**
|
|
|
|
When agents discover duplicate issues, they should:
|
|
1. Search for similar issues: `bd list --json | grep "similar text"`
|
|
2. Compare issue details: `bd show bd-41 bd-42 --json`
|
|
3. Merge duplicates: `bd merge bd-42 --into bd-41`
|
|
4. File a discovered-from issue if needed: `bd create "Found duplicates during bd-X" --deps discovered-from:bd-X`
|
|
|
|
## Git Worktrees
|
|
|
|
Git worktrees work with bd. Each worktree can have its own `.beads` directory, or worktrees can share a database via redirects (see [Database Redirects](#database-redirects)).
|
|
|
|
**With Dolt backend:** Each worktree operates directly on the database — no special coordination needed. Use `bd dolt push` to sync with Dolt remotes when ready.
|
|
|
|
**With Dolt server mode:** Multiple worktrees can connect to the same Dolt server for concurrent access without conflicts.
|
|
|
|
## Database Redirects
|
|
|
|
Multiple git clones can share a single beads database using redirect files. This is useful for:
|
|
- Multi-agent setups where several clones work on the same issues
|
|
- Development environments with multiple checkout directories
|
|
- Avoiding duplicate databases across clones
|
|
|
|
### Setting Up a Redirect
|
|
|
|
Create a `.beads/redirect` file pointing to the shared database location:
|
|
|
|
```bash
|
|
# In your secondary clone
|
|
mkdir -p .beads
|
|
echo "../main-clone/.beads" > .beads/redirect
|
|
|
|
# Or use an absolute path
|
|
echo "/path/to/shared/.beads" > .beads/redirect
|
|
```
|
|
|
|
The redirect file should contain a single path (relative or absolute) to the target `.beads` directory.
|
|
|
|
**Example setup:**
|
|
```
|
|
repo/
|
|
├── main-clone/
|
|
│ └── .beads/
|
|
│ └── beads.db ← Actual database
|
|
├── agent-1/
|
|
│ └── .beads/
|
|
│ └── redirect ← Points to ../main-clone/.beads
|
|
└── agent-2/
|
|
└── .beads/
|
|
└── redirect ← Points to ../main-clone/.beads
|
|
```
|
|
|
|
### Checking Active Location
|
|
|
|
Use `bd where` to see which database is actually being used:
|
|
|
|
```bash
|
|
bd where
|
|
# /path/to/main-clone/.beads
|
|
# (via redirect from /path/to/agent-1/.beads)
|
|
# prefix: bd
|
|
# database: /path/to/main-clone/.beads/beads.db
|
|
|
|
bd where --json
|
|
# {"path": "...", "redirected_from": "...", "prefix": "bd", "database_path": "..."}
|
|
```
|
|
|
|
### Limitations
|
|
|
|
- **Single-level redirects only**: Redirect chains are not followed (A → B → C won't work)
|
|
- **Target must exist**: The redirect target directory must exist and contain a valid database
|
|
|
|
### When to Use Redirects
|
|
|
|
**Good use cases:**
|
|
- Multiple AI agents working on the same project
|
|
- Parallel development clones (feature work, bug fixes)
|
|
- Testing clones that should see production issues
|
|
|
|
**Not recommended for:**
|
|
- Separate projects (use separate databases)
|
|
- Long-lived forks (they should have their own issues)
|
|
- Git worktrees (each should have its own `.beads` directory)
|
|
|
|
## Handling Merge Conflicts
|
|
|
|
**With hash-based IDs (v0.20.1+), ID collisions are eliminated.** Different issues get different hash IDs, so concurrent creation doesn't cause conflicts.
|
|
|
|
### Dolt Native Merge (Default)
|
|
|
|
Dolt handles merge conflicts natively with cell-level merge. When concurrent changes affect the same issue field, Dolt detects and resolves conflicts automatically where possible:
|
|
|
|
```bash
|
|
# Pull with automatic merge
|
|
bd dolt pull
|
|
|
|
# Check for unresolved conflicts
|
|
bd vc conflicts
|
|
|
|
# Resolve if needed
|
|
bd vc resolve
|
|
```
|
|
|
|
### Understanding Same-ID Scenarios
|
|
|
|
When you encounter the same ID during a Dolt pull or database bootstrap, it's an **update operation**, not a collision:
|
|
|
|
- Hash IDs are content-based and remain stable across updates
|
|
- Same ID + different fields = normal update to existing issue
|
|
- Dolt's cell-level merge resolves updates automatically
|
|
|
|
**Bootstrapping from an export:**
|
|
```bash
|
|
# Export from one database
|
|
bd export -o data.jsonl
|
|
|
|
# Bootstrap a new database from the export
|
|
bd init --from-jsonl
|
|
```
|
|
|
|
## Custom Git Hooks
|
|
|
|
Git hooks can be used to integrate beads with your git workflow:
|
|
|
|
### Using the Installer (Recommended)
|
|
|
|
```bash
|
|
bd hooks install
|
|
```
|
|
|
|
This installs hooks for beads data consistency checks during git operations.
|
|
|
|
See [DOLT.md](DOLT.md) for details on how the Dolt backend handles sync natively.
|
|
|
|
## Extensible Database
|
|
|
|
> **Note:** Custom table extensions via `UnderlyingDB()` are a **SQLite-only** pattern.
|
|
> With the Dolt backend, build standalone integration tools using bd's CLI with `--json`
|
|
> flags, or use `bd query` for direct SQL access.
|
|
|
|
For SQLite-backend users, you can extend bd with your own tables and queries:
|
|
|
|
- Add custom metadata to issues
|
|
- Build integrations with other tools
|
|
- Implement custom workflows
|
|
- Create reports and analytics
|
|
|
|
See [examples/bd-example-extension-go](../examples/bd-example-extension-go/README.md) for a working extension example.
|
|
|
|
## Architecture: Storage, RPC, and MCP
|
|
|
|
Understanding the role of each component:
|
|
|
|
### Beads (Core)
|
|
- **Dolt database** (primary) — Version-controlled SQL, the source of truth for all issues, dependencies, labels
|
|
- **SQLite database** (legacy) — Still supported for simple single-user setups
|
|
- **Storage layer** — Interface-based CRUD operations, dependency resolution, collision detection
|
|
- **Business logic** — Ready work calculation, merge operations, import/export
|
|
- **CLI commands** — Direct database access via `bd` command
|
|
|
|
### RPC Layer (Server Mode)
|
|
- **Multi-writer access** — Connects to a running Dolt server (`bd dolt start`) for concurrent clients
|
|
- **Used in multi-agent setups** — orchestrator environments where multiple agents write simultaneously
|
|
- **Not needed for single-user** — embedded mode handles all local operations without a server
|
|
|
|
### MCP Server (Optional)
|
|
- **Protocol adapter** — Translates MCP calls to direct CLI invocations
|
|
- **Workspace routing** — Finds correct `.beads` directory based on working directory
|
|
- **Stateless** — Doesn't cache or store any issue data itself
|
|
- **Editor integration** — Makes bd available to Claude, Cursor, and other MCP clients
|
|
|
|
**Key principle**: All heavy lifting (dependency graphs, collision resolution, merge logic) happens in the core bd storage layer. The RPC and MCP layers are thin adapters.
|
|
|
|
## Next Steps
|
|
|
|
- **[README.md](../README.md)** - Core features and quick start
|
|
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
|
|
- **[FAQ.md](FAQ.md)** - Frequently asked questions
|
|
- **[CONFIG.md](CONFIG.md)** - Configuration system guide
|
|
- **[examples/bd-example-extension-go](../examples/bd-example-extension-go/README.md)** - Working SQLite extension example
|