Merge pull request #2526 from maphew/fix/docs-purge-stale-refs

fix(docs): purge stale command/flag refs + add CI doc validation (GH#2522)
This commit is contained in:
Steve Yegge 2026-03-11 18:20:49 -07:00 • committed by GitHub
commit e42d222bae
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
45 changed files with 484 additions and 384 deletions

View file

@ -17,6 +17,24 @@ jobs:
- name: Check all versions match
run: ./scripts/check-versions.sh
# Check documentation references match actual CLI flags
check-doc-flags:
name: Check doc flags freshness
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Set up Go
uses: actions/setup-go@v6
with:
go-version-file: 'go.mod'
- name: Build bd
run: CGO_ENABLED=0 go build -o bd ./cmd/bd/
- name: Validate docs against CLI
run: ./scripts/check-doc-flags.sh ./bd
# Fast check to catch accidental .beads/issues.jsonl changes from contributors
check-no-beads-changes:
name: Check for .beads changes

View file

@ -93,9 +93,9 @@ bd hooks install
### Git Integration
**Dolt sync**: Dolt handles sync natively via `bd sync`. No JSONL export/import needed.
**Dolt sync**: Dolt handles sync natively via `bd dolt push` / `bd dolt pull`. No JSONL export/import needed.
**Protected branches**: Use `bd init --branch beads-metadata` to commit to separate branch. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md).
**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md).
**Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/ADVANCED.md](docs/ADVANCED.md).

View file

@ -160,6 +160,10 @@ fmt-check:
fi
@echo "All Go files are properly formatted"
# Validate documentation references against actual CLI flags
check-docs: build
@./scripts/check-doc-flags.sh ./bd
# Clean build artifacts and benchmark profiles
clean:
@echo "Cleaning..."
@ -181,5 +185,6 @@ help:
@echo " make install-force - Install bd, skipping the origin/main update check"
@echo " make fmt - Format all Go files with gofmt"
@echo " make fmt-check - Check Go formatting (for CI)"
@echo " make check-docs - Validate docs against CLI flags"
@echo " make clean - Remove build artifacts and profile files"
@echo " make help - Show this help message"

View file

@ -23,6 +23,6 @@ Each line is one event. Labeling is done by appending a new `"label"` event refe
## Notes
- Audit entries are **append-only** (no in-place edits).
- `bd sync` includes `.beads/interactions.jsonl` in the commit allowlist.
- `bd dolt push` includes `.beads/interactions.jsonl` in the commit allowlist.

View file

@ -1,36 +1,18 @@
---
description: Import issues from JSONL format
argument-hint: [-i input-file]
description: Import issues from JSONL format (removed)
argument-hint: (removed)
---
Import issues from JSON Lines format (one JSON object per line).
`bd import` has been **removed**.
## Usage
## Migration
- **From stdin**: `bd import` (reads from stdin)
- **From file**: `bd import -i issues.jsonl`
- **Preview**: `bd import -i issues.jsonl --dry-run`
## Behavior
- **Existing issues** (same ID): Updated with new data
- **New issues**: Created
- **Same-ID scenarios**: With hash-based IDs (v0.20.1+), same ID = same issue being updated (not a collision)
## Preview Changes
Use `--dry-run` to see what will change before importing:
If you need to import issues from a JSONL file, use `bd init` with the `--from-jsonl` flag:
```bash
bd import -i issues.jsonl --dry-run
# Shows: new issues, updates, exact matches
bd init <prefix> --from-jsonl issues.jsonl
```
## When to Use
## Note
Dolt is the primary storage backend, so manual import is rarely needed. Use `bd import` when you need to load data from an external JSONL file or migrate from a legacy JSONL-based setup.
## Options
- **--skip-existing**: Skip updates to existing issues
- **--strict**: Fail on dependency errors instead of warnings
Dolt is the primary storage backend. Manual JSONL import is no longer supported as a standalone command.

View file

@ -39,7 +39,7 @@ After closing, check if other work became ready:
- **Priority levels**: 0=critical, 1=high, 2=medium, 3=low, 4=backlog
- **Issue types**: bug, feature, task, epic, chore
- **Dependencies**: Use `blocks` for hard dependencies, `related` for soft links
- **Auto-sync**: Changes are stored in Dolt and synced via `bd sync`
- **Auto-sync**: Changes are stored in Dolt and synced via `bd dolt push` / `bd dolt pull`
## Available Commands
- `/beads:ready` - Find unblocked work

View file

@ -467,37 +467,7 @@ bd rename-prefix kw- --json # Apply rename
### Import/Export
```bash
# Import issues from JSONL
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
# 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 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.
> **Note:** `bd import` has been removed. For JSONL migration, use `bd init <prefix> --from-jsonl <file>`.
### Migration
@ -531,16 +501,15 @@ These invariants prevent data loss and would have caught issues like GH #201 (mi
### Sync Operations
```bash
# Manual sync (force immediate export/import/commit/push)
bd sync
# What it does:
# 1. Commit pending changes to Dolt
# 2. Pull from remote
# 3. Merge any updates
# 4. Push to remote
# Sync via Dolt commands
bd dolt push # Push changes to remote
bd dolt pull # Pull from remote
bd dolt commit # Commit pending changes
bd dolt show # Check connection status
```
> **Note:** `bd sync` is deprecated (now a no-op). Use the Dolt commands above instead.
## Issue Types
- `bug` - Something broken that needs fixing
@ -660,10 +629,10 @@ bd update bd-42 --claim --json
# ... work ...
# End of session (IMPORTANT!)
bd sync # Force immediate sync, bypass debounce
bd dolt push # Push changes to remote
```
**ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
**ALWAYS run `bd dolt push` at end of agent sessions** to ensure changes are pushed to remote.
## See Also

View file

@ -243,7 +243,7 @@ This is a **known SQLite limitation**, not a bd bug.
3. **Import existing issues (if you have a JSONL backup):**
```bash
bd import -i issues-backup.jsonl
bd init myproject --from-jsonl issues-backup.jsonl
```
**Alternative: Use global `~/.beads/` database**

View file

@ -73,8 +73,8 @@ bd duplicates --auto-merge
# Preview what would be merged
bd duplicates --dry-run
# Detect duplicates during import
bd import -i issues.jsonl --dedupe-after
# Detect duplicates after initializing from JSONL
bd init --from-jsonl # then: bd duplicates
```
**How it works:**
@ -255,25 +255,19 @@ bd vc resolve
### Understanding Same-ID Scenarios
When you encounter the same ID during import, it's an **update operation**, not a collision:
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
- bd automatically applies updates when importing
- Dolt's cell-level merge resolves updates automatically
**Preview changes before importing:**
**Bootstrapping from an export:**
```bash
# Preview an import
bd import -i data.jsonl --dry-run
# Export from one database
bd export -o data.jsonl
# Output shows:
# Exact matches (idempotent): 15
# New issues: 5
# Updates: 3
#
# Issues to be updated:
# bd-a3f2: Fix authentication (changed: priority, status)
# bd-b8e1: Add feature (changed: description)
# Bootstrap a new database from the export
bd init --from-jsonl
```
## Custom Git Hooks

View file

@ -49,7 +49,7 @@ bd's core design enables a distributed, git-backed issue tracker that feels like
**Dolt for distribution:** Native push/pull to Dolt remotes (DoltHub, S3, GCS). No special sync server needed. Issues travel with your code. Offline work just works.
**Import/export for portability:** `bd import` and `bd export` support JSONL format for data migration, bootstrapping new clones, and interoperability.
**Export for portability:** `bd export` outputs JSONL format for data migration and interoperability. Use `bd init --from-jsonl` to bootstrap a new database from an export.
## Write Path
@ -115,18 +115,18 @@ Branch B: bd create "Add Stripe" → bd-f14c (no collision)
1. **Issue creation:** Generate random UUID, derive short hash as ID
2. **Progressive scaling:** IDs start at 4 chars, grow to 5-6 chars as database grows
3. **Content hashing:** Each issue has a content hash for change detection
4. **Import merge:** Same ID + different content = update, same ID + same content = skip
4. **Merge logic:** Same ID + different content = update, same ID + same content = skip
```
┌─────────────────────────────────────────────────────────────────┐
│ Import Logic │
│ (used by bd import for migration) │
│ Merge Logic │
│ (used by Dolt pull and init --from-jsonl) │
│ │
│ For each issue in import data: │
│ For each issue in incoming data: │
│ 1. Compute content hash │
│ 2. Look up existing issue by ID │
│ 3. Compare hashes: │
│ - Same hash → skip (already imported) │
│ - Same hash → skip (already present) │
│ - Different hash → update (newer version) │
│ - No match → create (new issue) │
└─────────────────────────────────────────────────────────────────┘

View file

@ -41,14 +41,13 @@ Remote (Dolt remotes: DoltHub, S3, GCS, etc.)
- **Write path**: CLI → Dolt → auto-commit to Dolt history
- **Read path**: Direct SQL queries against Dolt
- **Sync**: Dolt handles versioning and sync natively; `bd import`/`bd export` available for migration
- **Sync**: Dolt handles versioning and sync natively; `bd export` available for data portability, `bd init --from-jsonl` for bootstrapping
- **Hash-based IDs**: Automatic collision prevention (v0.20+)
Core implementation:
- Dolt storage: `internal/storage/dolt/`
- Export: `cmd/bd/export.go`
- Import: `cmd/bd/import.go`
- Sync: `cmd/bd/sync_helpers.go`, `cmd/bd/sync_git.go`
- Sync: `cmd/bd/sync_git.go`
### Key Data Types

View file

@ -561,37 +561,26 @@ bd gate add-waiter <gate-id> <waiter>
## Database Management
### Import/Export
### Export / Bootstrap
```bash
# Import issues from JSONL
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
# Export issues to JSONL
bd export -o issues.jsonl
# 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
# Bootstrap a new database from an export
bd init --from-jsonl # Reads .beads/issues.jsonl
# Configure default orphan handling behavior
# Configure orphan handling for pulls and bootstrapping
bd config set import.orphan_handling "resurrect"
bd dolt push # Now uses resurrect mode by default
bd dolt pull # Respects import.orphan_handling setting
```
**Orphan handling modes:**
**Orphan handling modes** (apply to `bd dolt pull` and `bd init --from-jsonl`):
- **`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.
- **`resurrect`** - Search for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data.
- **`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
- **`strict`** - Fail immediately if a child's parent is missing. Use when database integrity is critical.
See [CONFIG.md](CONFIG.md#example-import-orphan-handling) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md#import-fails-with-missing-parent-errors) for more details.

View file

@ -73,7 +73,7 @@ A curated list of community-built UIs, extensions, and integrations for Beads. R
- **[jira-beads-sync](https://github.com/conallob/jira-beads-sync)** - CLI tool & Claude Code plugin to sync tasks from Jira into beads and publish beads task states back to Jira. Built by [@conallob](https://github.com/conallob). (Go)
- **[stringer](https://github.com/davetashner/stringer)** - Codebase archaeology CLI that mines git repos for TODOs, churn hotspots, lottery-risk files, dependency health, and more. Outputs JSONL for `bd import`. Install with `brew install davetashner/tap/stringer`. Built by [@davetashner](https://github.com/davetashner). (Go)
- **[stringer](https://github.com/davetashner/stringer)** - Codebase archaeology CLI that mines git repos for TODOs, churn hotspots, lottery-risk files, dependency health, and more. Outputs JSONL compatible with `bd init --from-jsonl`. Install with `brew install davetashner/tap/stringer`. Built by [@davetashner](https://github.com/davetashner). (Go)
## SDKs & Libraries

View file

@ -151,7 +151,7 @@ The sync mode controls how beads synchronizes data with git and/or Dolt remotes.
#### Sync Mode
Beads uses `dolt-native` sync mode exclusively. Dolt remotes handle sync directly with cell-level merge. Manual `bd import` / `bd export` are available for migration and portability.
Beads uses `dolt-native` sync mode exclusively. Dolt remotes handle sync directly with cell-level merge. Use `bd export` for data portability and `bd init --from-jsonl` to bootstrap a new database from an export.
#### Sync Triggers
@ -548,25 +548,24 @@ bd config set import.orphan_handling "allow"
**Mode details:**
- **`strict`** - Import fails immediately if a child's parent is missing. Use when database integrity is critical.
- **`resurrect`** - Searches the full JSONL file for missing parents and recreates them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis.
- **`strict`** - Fails immediately if a child's parent is missing. Use when database integrity is critical.
- **`resurrect`** - Searches for missing parents and recreates them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis.
- **`skip`** - Skips orphaned children with a warning. Partial import succeeds but some issues are excluded.
- **`allow`** - Imports orphans without parent validation. Most permissive, works around import bugs. **This is the default** because it ensures all data is imported even if hierarchy is temporarily broken.
- **`allow`** - Imports orphans without parent validation. Most permissive. **This is the default** because it ensures all data is imported even if hierarchy is temporarily broken.
These modes apply when bootstrapping a database with `bd init --from-jsonl` or when `bd dolt pull` merges remote data:
**Override per command:**
```bash
# Override config for a single import
bd import -i issues.jsonl --orphan-handling strict
# Auto-import (sync) uses config value
# Override config for a single pull
bd config set import.orphan_handling "resurrect"
bd dolt pull # Respects import.orphan_handling setting
```
**When to use each mode:**
- Use `allow` (default) for daily imports and auto-sync - ensures no data loss
- Use `resurrect` when importing from another database that had parent deletions
- Use `strict` only for controlled imports where you need to guarantee parent existence
- Use `allow` (default) for daily sync - ensures no data loss
- Use `resurrect` when pulling from remotes that had parent deletions
- Use `strict` only when you need to guarantee parent existence
- Use `skip` rarely - only when you want to selectively import a subset
### Example: Sync Safety Options

View file

@ -123,7 +123,7 @@ Beads uses `dolt-native` sync mode exclusively:
- Uses Dolt remotes (DoltHub, S3, GCS, etc.)
- Native database-level sync with cell-level merge
- Supports branching and merging
- `bd import`/`bd export` available for migration and portability
- `bd export` available for data portability; `bd init --from-jsonl` for bootstrapping from exports
## Dolt Remotes
@ -203,11 +203,8 @@ bd export -o backup.jsonl
# Archive existing beads
mv .beads .beads-sqlite-backup
# Initialize fresh
bd init
# Import from backup
bd import -i backup.jsonl
# Initialize fresh from backup
bd init --from-jsonl
```
## Troubleshooting

View file

@ -198,7 +198,7 @@ bd dolt push # Push changes to Dolt remote
bd dolt pull # Pull changes from Dolt remote
```
The `bd import` and `bd export` commands exist for data migration and portability (e.g., bootstrapping new clones, backing up data), not for day-to-day sync.
The `bd export` command exists for data portability (e.g., backing up data), and `bd init --from-jsonl` can bootstrap a new database from an export. These are not needed for day-to-day sync.
### What if my database feels stale after a colleague pushes changes?
@ -301,7 +301,7 @@ We don't have automated migration tools yet, but you can:
1. Export issues from your current tracker (usually CSV or JSON)
2. Write a simple script to convert to bd's JSONL format
3. Import with `bd import -i issues.jsonl`
3. Place the JSONL file at `.beads/issues.jsonl` and run `bd init --from-jsonl`
See [examples/](../examples/) for scripting patterns. Contributions welcome!
@ -434,15 +434,9 @@ See [WORKTREES.md](WORKTREES.md) for details.
### Why did beads create worktrees in my .git directory?
Beads automatically creates git worktrees when using the **sync-branch** feature. This happens when you:
- Run `bd init --branch <name>`
- Set `bd config set sync.branch <name>`
Older versions of beads created git worktrees for a **sync-branch** feature that has since been removed. Dolt now stores data under `refs/dolt/data`, separate from standard Git refs, so a separate branch is no longer needed.
The worktrees allow beads to commit issue updates to a separate branch without switching your working directory.
**Location:** `.git/beads-worktrees/<sync-branch>/`
**Common issue:** If you see "branch already checked out" errors when switching branches, remove the beads worktrees:
If you have leftover worktrees from an older version, you can safely remove them:
```bash
rm -rf .git/beads-worktrees

View file

@ -31,25 +31,15 @@ Git worktrees share the same `.git` directory and `.beads` database:
## Protected Branch Workflows
**If your repository uses protected branches** (GitHub, GitLab, etc.), bd can commit to a separate branch instead of `main`:
**Note:** Beads data is stored in Dolt under `refs/dolt/data`, separate from standard Git refs. This means beads does not commit to any Git branch, so protected branch workflows are not affected.
### Configuration
Sync with remotes using Dolt's native push/pull:
```bash
# Initialize with separate sync branch
bd init --branch beads-sync
# Or configure existing setup
bd config set sync.branch beads-sync
bd dolt push # Push changes to Dolt remote
bd dolt pull # Pull changes from Dolt remote
```
### How It Works
- Beads commits issue updates to `beads-sync` instead of `main`
- Uses git worktrees (lightweight checkouts) in `.git/beads-worktrees/`
- Your main working directory is never affected
- Periodically merge `beads-sync` back to `main` via pull request
### Daily Workflow (Unchanged for Agents)
```bash

View file

@ -15,9 +15,11 @@ This guide explains how to use beads with protected branches on platforms like G
## Overview
**Problem:** GitHub and other platforms let you protect branches (like `main`) to require pull requests for all changes. This prevents beads from auto-committing issue updates directly to `main`.
**Note:** This document describes a workflow that has been **removed**. Beads now stores data in Dolt under `refs/dolt/data`, separate from standard Git refs. Beads does not commit to any Git branch, so protected branch workflows are not affected.
**Solution:** Beads can commit to a separate branch (like `beads-sync`) using git worktrees, while keeping your main working directory untouched. Periodically merge the metadata branch back to `main` via a pull request.
**Previous problem:** GitHub and other platforms let you protect branches (like `main`) to require pull requests for all changes. Previously, beads committed issue data to Git branches, which conflicted with branch protection.
**Current solution:** Beads uses Dolt-native sync (`bd dolt push` / `bd dolt pull`). No Git branch commits are needed. The information below is retained for historical reference and for users migrating from older versions.
**Benefits:**
- ✅ Works with any git platform's branch protection
@ -33,10 +35,10 @@ This guide explains how to use beads with protected branches on platforms like G
```bash
cd your-project
bd init --branch beads-sync
bd init
```
This creates a `.beads/` directory and configures beads to commit to `beads-sync` instead of `main`.
This creates a `.beads/` directory with a Dolt database. Sync is handled via `bd dolt push` / `bd dolt pull`.
**Important:** After initialization, you'll see some untracked files that should be committed to your protected branch:
@ -50,7 +52,7 @@ git commit -m "Initialize beads issue tracker"
git push origin main # Or create a PR if required
```
**Files created by `bd init --branch`:**
**Files created by `bd init`:**
Files that should be committed to your protected branch (main):
- `.beads/.gitignore` - Tells git what to ignore in .beads/ directory
@ -142,13 +144,11 @@ When you update an issue:
```bash
cd your-project
bd init --branch beads-sync
bd init
```
This will:
- Create `.beads/` directory with database
- Set `sync.branch` config to `beads-sync`
- Import any existing issues from git (if present)
- Create `.beads/` directory with Dolt database
- Prompt to install git hooks (recommended: say yes)
### Option 2: Migrate Existing Project
@ -246,7 +246,7 @@ git push origin beads-sync
# 3. After PR is merged, update your local main
git checkout main
git pull
bd import # Import the merged changes
bd dolt pull # Pull latest changes
```
### Option 2: Direct Merge (If Allowed)
@ -254,14 +254,9 @@ bd import # Import the merged changes
If you have push access to `main`:
```bash
# Check what will be merged
git log main..beads-sync --oneline
# Merge sync branch to main
git checkout main
git merge beads-sync --no-ff
git push
bd import # Import merged changes to database
# Sync via Dolt (no git branch merge needed)
bd dolt push
bd dolt pull
```
**Safety checks:**
@ -385,9 +380,8 @@ No! This is a pure git solution that works on any platform. Just protect your `m
Yes! Use any branch name except `main` or `master` (git worktrees cannot checkout the same branch in multiple locations):
```bash
bd init --branch my-custom-branch
# or
bd config set sync.branch my-custom-branch
bd dolt remote add origin <remote-url>
bd dolt push
```
### Can I change the branch name later?
@ -608,7 +602,7 @@ git fetch upstream
# Merge upstream beads-sync to yours
git checkout beads-sync
git merge upstream/beads-sync
bd import # Import merged changes
bd dolt pull # Pull merged changes
```
### Custom Worktree Location

View file

@ -333,29 +333,26 @@ bd init
### `failed to import: issue already exists`
You're trying to import issues that conflict with existing ones. Options:
You're trying to bootstrap a database with issues that conflict with existing ones. Options:
```bash
# Skip existing issues (only import new ones)
bd import -i issues.jsonl --skip-existing
# Or clear database and re-import from an export
# Clear database and re-initialize from an export
rm -rf .beads/dolt
bd import -i backup.jsonl
bd init --from-jsonl
```
### Import fails with missing parent errors
If you see errors like `parent issue bd-abc does not exist` when importing hierarchical issues (e.g., `bd-abc.1`, `bd-abc.2`), this means the parent issue was deleted but children still reference it.
If you see errors like `parent issue bd-abc does not exist` when bootstrapping from JSONL or pulling hierarchical issues (e.g., `bd-abc.1`, `bd-abc.2`), this means the parent issue was deleted but children still reference it.
**Quick fix using resurrection:**
```bash
# Auto-resurrect deleted parents from import data
bd import -i issues.jsonl --orphan-handling resurrect
# Or set as default behavior
# Set orphan handling to auto-resurrect deleted parents
bd config set import.orphan_handling "resurrect"
# Then pull or re-initialize
bd dolt pull
```
**What resurrection does:**
@ -450,8 +447,8 @@ For **physical database corruption** (disk failures, power loss, filesystem erro
mv .beads/dolt .beads/dolt.backup
bd init
bd dolt pull # Pull from Dolt remote if configured
# Or import from a backup export:
# bd import -i backup.jsonl
# Or re-initialize from a backup export:
# bd init --from-jsonl
```
For **logical consistency issues** (ID collisions from branch merges, parallel workers):
@ -608,7 +605,7 @@ $ git checkout main
fatal: 'main' is already checked out at '/path/to/.git/beads-worktrees/beads-sync'
```
**Cause:** Beads creates git worktrees internally when using the sync-branch feature (configured via `bd init --branch` or `bd config set sync.branch`). These worktrees lock the branches they're checked out to.
**Cause:** Beads previously created git worktrees internally for a sync-branch feature (configured via `bd config set sync.branch`). These worktrees lock the branches they're checked out to. This feature has been removed; Dolt now stores data under `refs/dolt/data`, separate from standard Git refs.
**Solution:**
```bash
@ -825,7 +822,7 @@ See [integrations/beads-mcp/README.md](../integrations/beads-mcp/README.md) for
**Issue:** Sandboxed environments restrict permissions, preventing server control and causing "out of sync" errors.
**Common symptoms:**
- "Database out of sync" errors that persist after running `bd import`
- "Database out of sync" errors that persist after running `bd dolt pull`
- `bd dolt stop` fails with "operation not permitted"
- Hash mismatch warnings (bd-160)
@ -866,26 +863,24 @@ bd dolt push
If you're stuck in a "database out of sync" loop with a running server you can't stop, use these flags:
**1. Force metadata update (`--force` flag on import)**
**1. Force metadata update**
When `bd import` reports "0 created, 0 updated" but staleness persists:
If staleness persists after pulling:
```bash
# Force metadata refresh even when DB appears synced
bd import --force
# Force metadata refresh
bd doctor --fix
# This updates internal metadata tracking without changing issues
# Fixes: stuck state caused by stale server cache
```
**Shows:** `Metadata updated (database already in sync)`
**2. Use sandbox mode (preferred)**
```bash
# Most reliable for sandboxed environments
bd --sandbox ready
bd --sandbox import -i backup.jsonl
bd --sandbox dolt pull
```
---
@ -898,8 +893,8 @@ If stuck in a sandboxed environment:
# Step 1: Try sandbox mode (cleanest solution)
bd --sandbox ready
# Step 2: If you get staleness errors, force import
bd import --force
# Step 2: If you get staleness errors, force fix
bd doctor --fix
# Step 3: When back outside sandbox, sync normally
bd dolt push
@ -912,7 +907,7 @@ bd dolt push
| Flag | Purpose | When to use | Risk |
|------|---------|-------------|------|
| `--sandbox` | Use embedded mode, disable auto-sync | Sandboxed environments (Codex, containers) | Low - safe for sandboxes |
| `--force` (import) | Force metadata update | Stuck "0 created, 0 updated" loop | Low - updates metadata only |
| `bd doctor --fix` | Force metadata update | Stuck staleness loop | Low - updates metadata only |
**Related:**
- See [Claude Code sandboxing documentation](https://www.anthropic.com/engineering/claude-code-sandboxing) for more about sandbox restrictions

View file

@ -16,7 +16,9 @@ Beads now provides **enhanced Git worktree support** with a shared database arch
### Why Beads Creates Worktrees
When you configure a **sync branch** (via `bd init --branch <name>` or `bd config set sync.branch <name>`), beads needs to commit issue updates to that branch without switching your working directory away from your current branch.
**Note:** The sync-branch feature has been removed. Dolt now stores data under `refs/dolt/data`, separate from standard Git refs, so a separate branch is no longer needed. The information below applies only to older versions of beads.
When a **sync branch** was configured (via `bd config set sync.branch <name>`), beads needed to commit issue updates to that branch without switching your working directory away from your current branch.
**Solution:** Beads creates a lightweight worktree that:
- Contains only the `.beads/` directory (sparse checkout)
@ -264,7 +266,7 @@ bd config set sync.branch ""
**Symptoms:** You notice `.git/beads-worktrees/` or entries in `.git/worktrees/` that you didn't create.
**Cause:** Beads automatically creates worktrees when using the sync-branch feature (configured via `bd init --branch` or `bd config set sync.branch`).
**Cause:** Older versions of beads created worktrees for the sync-branch feature (configured via `bd config set sync.branch`). This feature has been removed.
**Solution:** See [Beads-Created Worktrees](#beads-created-worktrees-sync-branch) section above for details on what these are and how to remove them if unwanted.

View file

@ -77,8 +77,8 @@ If you're not using the Dolt server:
bd create "Fix bug in login" -t bug -p 0
bd update bd-XXXXX --status closed
# Manually flush to sync branch
bd sync --flush-only
# Manually push to remote
bd dolt push
# Verify commit
git log beads-metadata -1
@ -100,7 +100,7 @@ gh pr create --base main --head beads-metadata \
# After PR is approved and merged:
git checkout main
git pull
bd import # Import merged changes to database
bd dolt pull # Pull merged changes into local database
```
Option 2: Direct merge (if you have push access):
@ -113,7 +113,7 @@ git log main..beads-metadata --oneline
git checkout main
git merge beads-metadata --no-ff
git push
bd import # Import merged changes to database
bd dolt pull # Pull merged changes into local database
```
### 6. Multi-Clone Sync
@ -123,12 +123,12 @@ If you have multiple clones or agents:
```bash
# Clone 1: Create issue
bd create "New feature" -t feature -p 1
bd sync --flush-only # Commit to beads-metadata
bd dolt push # Push to remote
git push origin beads-metadata
# Clone 2: Pull changes
git fetch origin beads-metadata
bd sync --no-push # Pull from sync branch and import
bd dolt pull # Pull from remote into local database
bd list # See the new feature issue
```
@ -203,7 +203,7 @@ my-project/
- **No workflow changes:** Agents use `bd create`, `bd update`, etc. as normal
- **Let the Dolt server handle it:** With auto-commit enabled, agents don't think about sync
- **Session end:** Run `bd sync` at end of session to ensure everything is committed
- **Session end:** Run `bd dolt push` at end of session to ensure everything is pushed
### Troubleshooting
@ -212,7 +212,7 @@ my-project/
Dolt handles merges natively using three-way merge. If conflicts occur:
1. Run `bd sql "SELECT * FROM dolt_conflicts"` to view them
2. Resolve with `bd sql "CALL dolt_conflicts_resolve('--ours')"` or `'--theirs'`
3. Complete with `bd sync`
3. Complete with `bd dolt push`
**"Worktree doesn't exist"**
@ -276,4 +276,4 @@ jobs:
- [docs/PROTECTED_BRANCHES.md](../../docs/PROTECTED_BRANCHES.md) - Complete guide
- [AGENTS.md](../../AGENTS.md) - Agent integration instructions
- [commands/sync.md](../../claude-plugin/commands/sync.md) - `bd sync` command reference
- [docs/QUICKSTART.md](../../docs/QUICKSTART.md) - `bd dolt push` / `bd dolt pull` usage

View file

@ -67,7 +67,7 @@ If main isn't protected:
bd create "Implement feature X" -p 1
# Dolt server auto-commits to main
# (or run 'bd sync' manually)
# (or run 'bd dolt push' manually)
# Pull to see team's issues
git pull
@ -83,7 +83,7 @@ If main is protected:
bd create "Implement feature X" -p 1
# Auto-commits to beads-metadata branch
# (or run 'bd sync' manually)
# (or run 'bd dolt push' manually)
# Push beads-metadata
git push origin beads-metadata
@ -225,10 +225,11 @@ Benefits:
### Manual Sync
Sync when you want:
Push and pull when you want:
```bash
bd sync # Export, commit, pull, import, push
bd dolt push # Push local changes to remote
bd dolt pull # Pull remote changes locally
```
Benefits:
@ -238,7 +239,7 @@ Benefits:
## Conflict Resolution
Hash-based IDs prevent most conflicts. Dolt handles merges natively using three-way merge, similar to git. If conflicts occur during `bd sync`:
Hash-based IDs prevent most conflicts. Dolt handles merges natively using three-way merge, similar to git. If conflicts occur during `bd dolt pull`:
```bash
# View conflicts
@ -250,7 +251,7 @@ bd sql "CALL dolt_conflicts_resolve('--ours')"
bd sql "CALL dolt_conflicts_resolve('--theirs')"
# Complete the sync
bd sync
bd dolt push
```
## Protected Branch Best Practices
@ -291,10 +292,10 @@ bd sync
### Q: How do team members see each other's issues?
A: Issues are stored in Dolt, which supports distributed sync. Use `bd sync` to pull and push changes.
A: Issues are stored in Dolt, which supports distributed sync. Use `bd dolt pull` to fetch and `bd dolt push` to share changes.
```bash
bd sync
bd dolt pull
bd list # See everyone's issues
```
@ -310,7 +311,8 @@ A: Turn it off:
bd config set dolt.auto-commit off
# Sync manually
bd sync
bd dolt push
bd dolt pull
```
### Q: Can we use different sync branches per person?
@ -329,7 +331,7 @@ A: Add to your CI pipeline:
# In .github/workflows/main.yml
- name: Sync beads issues
run: |
bd sync
bd dolt push
git push origin beads-metadata
```
@ -363,7 +365,7 @@ Dolt handles merges natively. If conflicts occur during sync:
```bash
bd sql "SELECT * FROM dolt_conflicts"
bd sql "CALL dolt_conflicts_resolve('--ours')"
bd sync
bd dolt push
```
See [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md) for details.
@ -373,8 +375,8 @@ See [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md) for details.
Manually sync:
```bash
bd sync
git push
bd dolt push
bd dolt pull
```
Check for conflicts:

View file

@ -82,7 +82,7 @@ bd setup junie --remove
- `bd prime` - Get full workflow context
- `bd ready` - Find unblocked work
- `bd sync` - Sync changes to git (run at session end)
- `bd dolt push` - Push issue changes to Dolt remote (run at session end)
## License

View file

@ -305,7 +305,7 @@ While working:
When done:
- Close the issue: `bd close <id> --reason "Description of what was done"`
- Run `bd sync` to push issue changes
- Run `bd dolt push` to push issue changes
```
## Alternative: Package as Project Dependency

View file

@ -99,7 +99,7 @@ bd dep tree <issue-id>
2. **Create issues proactively**: When you notice work, file it immediately
3. **Link discovered work**: Use `bd dep add --type discovered-from`
4. **Close with context**: Always provide --reason when closing
5. **Sync changes**: Run `bd sync` to push changes to the Dolt remote
5. **Sync changes**: Run `bd dolt push` to push changes to the Dolt remote
```
### Step 4: Commit and Push
@ -275,7 +275,7 @@ bd init
**Cause**: Two sessions modified issues concurrently
**Fix**: Run `bd sync` to resolve via Dolt's merge. See the main beads TROUBLESHOOTING.md for details.
**Fix**: Run `bd dolt pull` to resolve via Dolt's merge. See the main beads TROUBLESHOOTING.md for details.
### Slow Installation
@ -319,20 +319,20 @@ WORKFLOW:
5. File new issues: Create issues for any work discovered
6. Link issues: Use `bd dep add` to track relationships
7. Close when done: `bd close <id> --reason "what you did"`
8. Sync changes: Run `bd sync` at end of session
8. Sync changes: Run `bd dolt push` at end of session
ALWAYS:
- Use --json flags for programmatic parsing
- Create issues proactively (don't let work be forgotten)
- Link related issues with dependencies
- Close issues with descriptive reasons
- Run `bd sync` at end of sessions
- Run `bd dolt push` at end of sessions
NEVER:
- Use markdown TODOs (use bd instead)
- Work on blocked issues (check `bd show <id>` for blockers)
- Close issues without --reason
- Forget to run `bd sync` at end of sessions
- Forget to run `bd dolt push` at end of sessions
```
## 🎉 Success Criteria

178
scripts/check-doc-flags.sh Executable file
View file

@ -0,0 +1,178 @@
#!/bin/bash
# check-doc-flags.sh — Validate documentation references against actual CLI flags.
#
# This script catches stale doc references by:
# 1. Extracting all flags from `bd help --all`
# 2. Scanning docs for `bd <command> --<flag>` patterns
# 3. Flagging any that don't exist in the CLI
#
# Also checks for references to known-removed commands (bd sync, bd import).
#
# Usage: ./scripts/check-doc-flags.sh [bd-binary]
#
# Exit codes:
# 0 - All docs are consistent with CLI
# 1 - Stale references found
set -euo pipefail
BD="${1:-bd}"
ERRORS=0
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
# Verify bd binary exists and runs
if ! command -v "$BD" &>/dev/null && [ ! -x "$BD" ]; then
echo "Error: bd binary not found at '$BD'"
echo "Usage: $0 [path-to-bd]"
exit 1
fi
echo "Checking documentation against CLI flags..."
echo "Using: $($BD version 2>/dev/null | head -1 || echo "$BD")"
echo ""
# --- Check 1: Known-removed commands ---
echo "=== Check 1: Removed commands ==="
# bd sync (removed in v0.51)
SYNC_REFS=$(grep -rn 'bd sync\b' \
"$PROJECT_ROOT"/docs/*.md \
"$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \
"$PROJECT_ROOT"/AGENTS.md \
"$PROJECT_ROOT"/README.md \
"$PROJECT_ROOT"/npm-package/*.md \
"$PROJECT_ROOT"/integrations/*/README.md \
"$PROJECT_ROOT"/website/docs/**/*.md \
"$PROJECT_ROOT"/claude-plugin/commands/*.md \
"$PROJECT_ROOT"/claude-plugin/skills/beads/resources/*.md \
2>/dev/null \
| grep -v 'CHANGELOG\|audit-sync-mode\|deprecated\|no-op\|removed\|was removed\|has been removed' \
|| true)
if [ -n "$SYNC_REFS" ]; then
echo "FAIL: Found references to removed 'bd sync' command:"
echo "$SYNC_REFS" | head -20
ERRORS=$((ERRORS + 1))
else
echo "PASS: No stale 'bd sync' references"
fi
# bd import (removed)
IMPORT_REFS=$(grep -rn 'bd import\b' \
"$PROJECT_ROOT"/docs/*.md \
"$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \
"$PROJECT_ROOT"/AGENTS.md \
"$PROJECT_ROOT"/README.md \
"$PROJECT_ROOT"/npm-package/*.md \
"$PROJECT_ROOT"/integrations/*/README.md \
"$PROJECT_ROOT"/website/docs/**/*.md \
"$PROJECT_ROOT"/claude-plugin/commands/*.md \
"$PROJECT_ROOT"/claude-plugin/skills/beads/resources/*.md \
2>/dev/null \
| grep -v 'CHANGELOG\|removed\|was removed\|has been removed\|no longer\|deprecated\|REMOVED\|DISCOVERY' \
|| true)
if [ -n "$IMPORT_REFS" ]; then
echo "FAIL: Found references to removed 'bd import' command:"
echo "$IMPORT_REFS" | head -20
ERRORS=$((ERRORS + 1))
else
echo "PASS: No stale 'bd import' references"
fi
echo ""
# --- Check 2: bd init flags ---
echo "=== Check 2: bd init flags ==="
# Get actual init flags
INIT_FLAGS=$($BD init --help 2>&1 | grep -oP '^\s+--[a-z][a-z0-9-]*' | sed 's/^\s*//' || true)
# Check for --branch on init (removed)
BRANCH_REFS=$(grep -rn 'bd init.*--branch' \
"$PROJECT_ROOT"/docs/*.md \
"$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \
"$PROJECT_ROOT"/AGENTS.md \
"$PROJECT_ROOT"/README.md \
"$PROJECT_ROOT"/website/docs/**/*.md \
2>/dev/null \
| grep -v 'CHANGELOG\|removed\|was removed\|no longer\|deprecated' \
|| true)
if [ -n "$BRANCH_REFS" ]; then
echo "FAIL: Found references to removed 'bd init --branch' flag:"
echo "$BRANCH_REFS" | head -20
ERRORS=$((ERRORS + 1))
else
echo "PASS: No stale 'bd init --branch' references"
fi
echo ""
# --- Check 3: SQLite/legacy database paths ---
echo "=== Check 3: Legacy storage references ==="
SQLITE_REFS=$(grep -rn 'beads\.db\|default\.db\|sqlite3.*\.beads\|\.beads/.*\.db' \
"$PROJECT_ROOT"/docs/*.md \
"$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \
"$PROJECT_ROOT"/AGENTS.md \
"$PROJECT_ROOT"/README.md \
"$PROJECT_ROOT"/website/docs/**/*.md \
2>/dev/null \
| grep -v 'CHANGELOG\|removed\|legacy\|migration\|migrate\|was removed\|pre-\|old\|deprecated' \
|| true)
if [ -n "$SQLITE_REFS" ]; then
echo "WARN: Found possible legacy SQLite/database references:"
echo "$SQLITE_REFS" | head -20
# Don't increment ERRORS — these may be intentional migration docs
else
echo "PASS: No stale SQLite references"
fi
echo ""
# --- Check 4: CLI_REFERENCE.md freshness (if help --all available) ---
echo "=== Check 4: CLI_REFERENCE.md freshness ==="
CLI_REF="$PROJECT_ROOT/docs/CLI_REFERENCE.md"
if [ -f "$CLI_REF" ]; then
TMPDIR_CHECK=$(mktemp -d)
trap "rm -rf $TMPDIR_CHECK" EXIT
if timeout 30 $BD help --all > "$TMPDIR_CHECK/help-all.md" 2>/dev/null; then
# Extract top-level command names from help output
grep -oP '## bd [a-z][-a-z]*$' "$TMPDIR_CHECK/help-all.md" \
| sed 's/## bd //' | sort -u > "$TMPDIR_CHECK/help-cmds.txt"
# Extract command names referenced in CLI_REFERENCE.md
grep -oP '\bbd [a-z][-a-z]+\b' "$CLI_REF" \
| sed 's/^bd //' | sort -u > "$TMPDIR_CHECK/doc-cmds.txt"
MISSING=$(comm -23 "$TMPDIR_CHECK/help-cmds.txt" "$TMPDIR_CHECK/doc-cmds.txt" || true)
if [ -n "$MISSING" ]; then
echo "INFO: Commands in CLI not mentioned in CLI_REFERENCE.md (may be OK):"
echo "$MISSING" | head -10
else
echo "PASS: CLI_REFERENCE.md covers all CLI commands"
fi
else
echo "SKIP: bd help --all timed out or unavailable"
fi
else
echo "SKIP: docs/CLI_REFERENCE.md not found"
fi
echo ""
# --- Summary ---
echo "=== Summary ==="
if [ $ERRORS -gt 0 ]; then
echo "FAILED: $ERRORS stale reference category(ies) found"
echo ""
echo "To fix: update the referenced docs to use current CLI commands."
echo "See docs/DOLT-BACKEND.md for current sync workflow."
exit 1
else
echo "PASSED: All documentation references are consistent with CLI"
exit 0
fi

View file

@ -34,7 +34,7 @@ flowchart TD
:::info Source of Truth
**Dolt** is the source of truth. Every write auto-commits to Dolt history, providing full version control, branching, and merge capabilities at the database level.
Recovery is straightforward: pull from a Dolt remote, or use `bd import` to load from a JSONL backup.
Recovery is straightforward: pull from a Dolt remote with `bd dolt pull`, or use `bd init --from-jsonl` to bootstrap from a JSONL backup.
:::
### Why Dolt?
@ -109,7 +109,7 @@ For CI/CD pipelines, containers, and single-use scenarios, no server is needed.
```bash
bd create "CI-generated issue"
bd sync
bd dolt push
```
**When embedded mode is appropriate:**
@ -139,7 +139,7 @@ See [Sync Failures Recovery](/recovery/sync-failures) for sync race condition tr
Dolt's version control makes recovery straightforward:
1. **Lost database?** → Pull from Dolt remote: `bd dolt pull`
2. **Have a JSONL backup?** → Import it: `bd import -i backup.jsonl`
2. **Have a JSONL backup?** → Bootstrap from it: `bd init --from-jsonl backup.jsonl`
3. **Merge conflicts?** → Dolt handles cell-level merge natively
### Universal Recovery Sequence

View file

@ -158,22 +158,34 @@ bd blocked
bd blocked --json
```
## bd sync
## bd dolt push
Force immediate sync to git.
Push changes to a Dolt remote.
```bash
bd sync [flags]
bd dolt push [flags]
```
Performs:
1. Dolt commit (snapshot current database state)
2. Dolt push to remote
2. Push to Dolt remote
**Examples:**
```bash
bd sync
bd sync --json
bd dolt push
```
## bd dolt pull
Pull changes from a Dolt remote.
```bash
bd dolt pull [flags]
```
**Examples:**
```bash
bd dolt pull
```
## bd info

View file

@ -39,7 +39,8 @@ Most frequently used:
| `bd update` | Update issue fields |
| `bd close` | Close an issue |
| `bd ready` | Show unblocked work |
| `bd sync` | Force sync to git |
| `bd dolt push` | Push changes to Dolt remote |
| `bd dolt pull` | Pull changes from Dolt remote |
### Issue Management
@ -77,9 +78,9 @@ Most frequently used:
| Command | Description |
|---------|-------------|
| `bd sync` | Full sync cycle |
| `bd dolt push` | Push changes to Dolt remote |
| `bd dolt pull` | Pull changes from Dolt remote |
| `bd export` | Export data to JSONL |
| `bd import` | Import data from JSONL |
| `bd migrate` | Migrate database schema |
### System
@ -165,14 +166,14 @@ bd blocked
### Syncing
```bash
# Full sync (Dolt commit + push)
bd sync
# Push changes to Dolt remote
bd dolt push
# Pull changes from Dolt remote
bd dolt pull
# Export to file
bd export -o backup.jsonl
# Import from file
bd import -i backup.jsonl
```
## See Also

View file

@ -8,35 +8,50 @@ sidebar_position: 6
Commands for synchronizing with Dolt.
## bd sync
## bd dolt push
Full sync cycle: Dolt commit and push.
Push changes to a Dolt remote.
```bash
bd sync [flags]
bd dolt push [flags]
```
**What it does:**
1. Dolt commit (snapshot current database state)
2. Dolt push to remote
**Flags:**
```bash
--json JSON output
--dry-run Preview without changes
```
2. Push commits to Dolt remote
**Examples:**
```bash
bd sync
bd sync --json
bd dolt push
```
**When to use:**
- End of work session
- Before switching branches
- Before switching machines
- After significant changes
## bd dolt pull
Pull changes from a Dolt remote.
```bash
bd dolt pull [flags]
```
**What it does:**
1. Fetches commits from Dolt remote
2. Merges into local database
**Examples:**
```bash
bd dolt pull
```
**When to use:**
- Start of work session
- After switching machines
- Before creating new issues (to avoid duplicates)
## bd export
Export database to JSONL format (for backup and migration).
@ -61,41 +76,6 @@ bd export --dry-run
**When to use:** `bd export` is for backup and data migration, not day-to-day sync. Dolt handles sync natively via `bd dolt push`/`bd dolt pull`.
## bd import
Import from JSONL file (for migration and recovery).
```bash
bd import -i <file> [flags]
```
**Flags:**
```bash
--input, -i Input file (required)
--dry-run Preview without changes
--orphan-handling How to handle missing parents
--dedupe-after Run duplicate detection after import
--json JSON output
```
**Orphan handling modes:**
| Mode | Behavior |
|------|----------|
| `allow` | Import orphans without validation (default) |
| `resurrect` | Restore deleted parents as tombstones |
| `skip` | Skip orphaned children with warning |
| `strict` | Fail if parent missing |
**Examples:**
```bash
bd import -i backup.jsonl
bd import -i backup.jsonl --dry-run
bd import -i issues.jsonl --orphan-handling resurrect
bd import -i issues.jsonl --dedupe-after --json
```
**When to use:** `bd import` is for loading data from external JSONL files or migrating from a legacy setup. For day-to-day sync, use `bd dolt push`/`bd dolt pull`.
## bd migrate
Migrate database schema.
@ -157,21 +137,21 @@ Start the Dolt server with `bd dolt start`.
In CI/CD pipelines and ephemeral environments, no server is needed:
- Changes written directly to the database
- Must manually sync
- Must manually push to remote
```bash
bd create "CI-generated task"
bd sync # Manual sync needed
bd dolt push # Manual push needed
```
## Conflict Resolution
Dolt handles conflict resolution at the database level using its built-in
merge capabilities. When conflicts arise during `dolt pull`, Dolt identifies
merge capabilities. When conflicts arise during `bd dolt pull`, Dolt identifies
conflicting rows and allows resolution through SQL.
```bash
# Check for conflicts after sync
# Check for conflicts after pull
bd doctor --fix
```
@ -187,12 +167,13 @@ bd delete bd-42
bd deleted
bd deleted --since=30d
# Deletions propagate via Dolt sync
bd sync
# Deletions propagate via Dolt push
bd dolt push
```
## Best Practices
1. **Always sync at session end** - `bd sync`
2. **Install git hooks** - `bd hooks install`
3. **Check sync status** - `bd info` shows sync state
1. **Always push at session end** - `bd dolt push`
2. **Always pull at session start** - `bd dolt pull`
3. **Install git hooks** - `bd hooks install`
4. **Check sync status** - `bd info` shows sync state

View file

@ -114,8 +114,8 @@ bd list --full-ids
If migrating from a system with sequential IDs:
```bash
# Import preserves original IDs in metadata
bd import -i old-issues.json
# 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'

View file

@ -19,7 +19,7 @@ bd setup claude
This installs:
- **SessionStart hook** - Runs `bd prime` when Claude Code starts
- **PreCompact hook** - Ensures `bd sync` before context compaction
- **PreCompact hook** - Ensures `bd dolt push` before context compaction
**How it works:**
1. SessionStart hook runs `bd prime` automatically
@ -40,7 +40,7 @@ If you prefer manual configuration, add to your Claude Code hooks:
{
"hooks": {
"SessionStart": ["bd prime"],
"PreCompact": ["bd sync"]
"PreCompact": ["bd dolt push"]
}
}
```

View file

@ -26,7 +26,8 @@ bd init --contributor
bd init --team
# Protected main branch (GitHub/GitLab)
bd init --branch beads-sync
# Note: Dolt stores data under refs/dolt/data, separate from
# Git refs, so no --branch flag is needed.
```
The wizard will:

View file

@ -119,11 +119,16 @@ bd migrate --dry-run
bd migrate
```
### Import errors after upgrade
### Recovery after upgrade
Check the import configuration:
If you need to restore from a JSONL backup:
```bash
bd config get import.orphan_handling
bd import -i backup.jsonl --orphan-handling allow
bd init --from-jsonl backup.jsonl
```
Or pull from a Dolt remote:
```bash
bd dolt pull
```

View file

@ -59,13 +59,13 @@ bd ready
### End Session
```bash
bd sync
bd dolt push
```
## Best Practices
1. **Keep issues visible** - Use `bd prime` to inject issue context
2. **Sync regularly** - Run `bd sync` after significant changes
2. **Push regularly** - Run `bd dolt push` after significant changes
3. **Use discovered-from** - Track issues found during work
4. **Document context** - Include descriptions in issues
@ -83,9 +83,9 @@ aider --message "Working on bd-42: Fix auth bug"
# 4. Create discovered issues
bd create "Found related bug" --deps discovered-from:bd-42 --json
# 5. Complete and sync
# 5. Complete and push
bd close bd-42 --reason "Fixed"
bd sync
bd dolt push
```
## Troubleshooting

View file

@ -18,7 +18,7 @@ bd setup claude
This installs:
- **SessionStart hook** - Runs `bd prime` on session start
- **PreCompact hook** - Runs `bd sync` before context compaction
- **PreCompact hook** - Runs `bd dolt push` before context compaction
### Manual Setup
@ -28,7 +28,7 @@ Add to your Claude Code hooks configuration:
{
"hooks": {
"SessionStart": ["bd prime"],
"PreCompact": ["bd sync"]
"PreCompact": ["bd dolt push"]
}
}
```
@ -43,7 +43,7 @@ bd setup claude --check
1. **Session starts** → `bd prime` injects ~1-2k tokens of context
2. **You work** → Use `bd` CLI commands directly
3. **Session compacts** → `bd sync` saves work to git
3. **Session compacts** → `bd dolt push` saves work to Dolt remote
4. **Session ends** → Changes synced via git
## Essential Commands for Agents
@ -92,7 +92,7 @@ bd blocked --json
```bash
# ALWAYS run at session end
bd sync
bd dolt push
```
## Best Practices
@ -125,11 +125,11 @@ bd create "Found related bug" \
--deps discovered-from:bd-current --json
```
### Sync Before Session End
### Push Before Session End
```bash
# ALWAYS run before ending
bd sync
bd dolt push
```
## Plugin (Optional)
@ -165,8 +165,8 @@ bd prime
### Changes not syncing
```bash
# Force sync
bd sync
# Force push
bd dolt push
# Check system health
bd doctor

View file

@ -82,7 +82,7 @@ Copilot: Closed bd-42
| `beads_show` | Show issue details |
| `beads_update` | Update issue |
| `beads_close` | Close issue |
| `beads_sync` | Sync to git |
| `beads_dolt_push` | Push to Dolt remote |
| `beads_dep_add` | Add dependency |
| `beads_dep_tree` | Show dependency tree |
@ -100,7 +100,7 @@ Quick reference:
- `bd ready` - Find unblocked work
- `bd create "Title" --type task --priority 2` - Create issue
- `bd close <id>` - Complete work
- `bd sync` - Sync with git
- `bd dolt push` - Push changes to Dolt remote
```
## Troubleshooting
@ -136,7 +136,7 @@ bd init --quiet
### What about git hooks?
Git hooks are optional. They auto-sync issues but you can skip them during `bd init` and manually run `bd sync` instead.
Git hooks are optional. They auto-sync issues but you can skip them during `bd init` and manually run `bd dolt push` / `bd dolt pull` instead.
## See Also

View file

@ -31,7 +31,7 @@ bd setup junie --check
1. **Session starts** → Junie reads `.junie/guidelines.md` for workflow context
2. **MCP tools available** → Junie can use beads MCP tools directly
3. **You work** → Use `bd` CLI commands or MCP tools
4. **Session ends** → Run `bd sync` to save work to git
4. **Session ends** → Run `bd dolt push` to push changes to Dolt remote
## Configuration Files
@ -122,7 +122,7 @@ bd blocked --json
```bash
# ALWAYS run at session end
bd sync
bd dolt push
```
## Best Practices
@ -155,11 +155,11 @@ bd create "Found related bug" \
--deps discovered-from:bd-current --json
```
### Sync Before Session End
### Push Before Session End
```bash
# ALWAYS run before ending
bd sync
bd dolt push
```
## Troubleshooting
@ -187,8 +187,8 @@ bd mcp --help
### Changes not syncing
```bash
# Force sync
bd sync
# Force push
bd dolt push
# Check system health
bd doctor

View file

@ -63,8 +63,8 @@ bd show bd-42 --json
bd create "Found bug in auth" --description="Details..." \
--deps discovered-from:bd-100 --json
# Sync at end of session
bd sync
# Push changes at end of session
bd dolt push
```
See the [Claude Code integration](/integrations/claude-code) for detailed agent instructions.

View file

@ -15,7 +15,7 @@ This section provides step-by-step recovery procedures for common Beads issues.
| Database Corruption | SQLite errors, missing data | [Database Corruption](/recovery/database-corruption) |
| Merge Conflicts | Dolt conflicts during sync | [Merge Conflicts](/recovery/merge-conflicts) |
| Circular Dependencies | Cycle detection errors | [Circular Dependencies](/recovery/circular-dependencies) |
| Sync Failures | `bd sync` errors | [Sync Failures](/recovery/sync-failures) |
| Sync Failures | `bd dolt push`/`bd dolt pull` errors | [Sync Failures](/recovery/sync-failures) |
## Quick Diagnostic

View file

@ -115,7 +115,8 @@ Events:
### Create Multiple
```bash
cat issues.jsonl | bd import -i -
# Bootstrap a new database from JSONL
bd init --from-jsonl issues.jsonl
```
### Update Multiple

View file

@ -94,7 +94,7 @@ path = ".beads/issues.jsonl" # Default export file path (for bd export command)
[git]
auto_commit = true # Auto-commit on sync
auto_push = true # Auto-push on sync
commit_message = "bd sync" # Default commit message
commit_message = "bd: auto-commit" # Default commit message
```
### Hooks

View file

@ -52,19 +52,22 @@ In CI/CD or single-agent environments, beads uses embedded mode automatically (n
## Usage
### How do I sync issues to git?
### How do I sync issues?
```bash
# Manual sync:
bd sync
# Push changes to Dolt remote:
bd dolt push
# Pull changes from Dolt remote:
bd dolt pull
```
### How do I handle merge conflicts?
Dolt handles merge conflicts at the database level. If conflicts arise during sync:
Dolt handles merge conflicts at the database level. If conflicts arise during pull:
```bash
bd doctor --fix
bd sync
bd dolt push
```
### Can multiple agents work on the same repo?
@ -120,10 +123,7 @@ bd setup aider # Aider
### Can beads import from GitHub Issues?
Yes:
```bash
bd import --from github --repo owner/repo
```
Yes — see the [GitHub integration documentation](https://github.com/steveyegge/beads/blob/main/docs/GITHUB_IMPORT.md) for details.
## Troubleshooting
@ -144,8 +144,8 @@ bd dolt start
### Why aren't my changes syncing?
```bash
# Force sync
bd sync
# Force push to Dolt remote
bd dolt push
# Check hooks
bd hooks status

View file

@ -63,16 +63,7 @@ bd doctor --fix
## Protected Branches
For protected main branches:
```bash
bd init --branch beads-sync
```
This:
- Creates a separate `beads-sync` branch
- Syncs issues to that branch
- Avoids direct commits to main
Dolt stores data under `refs/dolt/data`, separate from Git refs. This means beads data doesn't conflict with protected Git branches — no special branch flag is needed.
## Git Worktrees
@ -92,7 +83,7 @@ bd list
git checkout -b feature-x
bd create "Feature X" -t feature
# Work...
bd sync
bd dolt push
git push
```
@ -102,7 +93,7 @@ git push
# In fork
bd init --contributor
# Work in separate planning repo...
bd sync
bd dolt push
```
### Team Workflow
@ -110,7 +101,8 @@ bd sync
```bash
bd init --team
# All team members share the Dolt database
bd sync # Pulls latest changes via Dolt replication
bd dolt pull # Pull latest changes from Dolt remote
bd dolt push # Push your changes to Dolt remote
```
### Duplicate Detection
@ -124,6 +116,6 @@ bd duplicates --auto-merge
## Best Practices
1. **Install hooks** - `bd hooks install`
2. **Sync regularly** - `bd sync` at session end
3. **Pull before work** - Get latest issues
2. **Push regularly** - `bd dolt push` at session end
3. **Pull before work** - `bd dolt pull` to get latest issues
4. **Worktrees use embedded mode automatically**

View file

@ -69,8 +69,8 @@ bd doctor --fix
# Or pull from Dolt remote
bd dolt pull
# Or restore from a JSONL backup if available
bd import -i backup.jsonl
# Or bootstrap from a JSONL backup if available
bd init --from-jsonl backup.jsonl
```
## Dolt Server Issues
@ -103,21 +103,21 @@ bd dolt start
### Changes not syncing
```bash
# Force sync
bd sync
# Force push to Dolt remote
bd dolt push
# Check hooks
bd hooks status
```
### Import errors
### Recovery from backup
```bash
# Allow orphans
bd import -i backup.jsonl --orphan-handling allow
# Bootstrap from JSONL backup
bd init --from-jsonl backup.jsonl
# Check for duplicates after
bd duplicates
# Or pull from Dolt remote
bd dolt pull
```
### Merge conflicts
@ -126,8 +126,8 @@ bd duplicates
# Check for and fix Dolt conflicts
bd doctor --fix
# Re-sync
bd sync
# Re-push
bd dolt push
```
## Git Hook Issues