diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8e66853d5..ec65d4458 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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 diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md index 0682a3b11..42429cd80 100644 --- a/AGENT_INSTRUCTIONS.md +++ b/AGENT_INSTRUCTIONS.md @@ -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). diff --git a/Makefile b/Makefile index 19f3cfeb1..f7202f62c 100644 --- a/Makefile +++ b/Makefile @@ -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" diff --git a/claude-plugin/commands/audit.md b/claude-plugin/commands/audit.md index 7d0dcc537..ff1a6649e 100644 --- a/claude-plugin/commands/audit.md +++ b/claude-plugin/commands/audit.md @@ -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. diff --git a/claude-plugin/commands/import.md b/claude-plugin/commands/import.md index 3b435a4e5..bd00c7de1 100644 --- a/claude-plugin/commands/import.md +++ b/claude-plugin/commands/import.md @@ -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 --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. diff --git a/claude-plugin/commands/workflow.md b/claude-plugin/commands/workflow.md index fe39f3753..8e2d5e55e 100644 --- a/claude-plugin/commands/workflow.md +++ b/claude-plugin/commands/workflow.md @@ -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 diff --git a/claude-plugin/skills/beads/resources/CLI_REFERENCE.md b/claude-plugin/skills/beads/resources/CLI_REFERENCE.md index 7d4e3d59c..b157748e6 100644 --- a/claude-plugin/skills/beads/resources/CLI_REFERENCE.md +++ b/claude-plugin/skills/beads/resources/CLI_REFERENCE.md @@ -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 --from-jsonl `. ### 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 diff --git a/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md b/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md index b62a87518..9d4dc70e3 100644 --- a/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md +++ b/claude-plugin/skills/beads/resources/TROUBLESHOOTING.md @@ -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** diff --git a/docs/ADVANCED.md b/docs/ADVANCED.md index bb41db2b4..26d72ef4b 100644 --- a/docs/ADVANCED.md +++ b/docs/ADVANCED.md @@ -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 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index f7cafaa09..89a20fe62 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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) │ └─────────────────────────────────────────────────────────────────┘ diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index 98ab7920c..07cd6f0db 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -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 diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 3be9edede..a7d1f44e9 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -561,37 +561,26 @@ bd gate add-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. diff --git a/docs/COMMUNITY_TOOLS.md b/docs/COMMUNITY_TOOLS.md index e8049801a..019807d96 100644 --- a/docs/COMMUNITY_TOOLS.md +++ b/docs/COMMUNITY_TOOLS.md @@ -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 diff --git a/docs/CONFIG.md b/docs/CONFIG.md index ba98f1104..a797c000d 100644 --- a/docs/CONFIG.md +++ b/docs/CONFIG.md @@ -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 diff --git a/docs/DOLT-BACKEND.md b/docs/DOLT-BACKEND.md index 22e99d0eb..120acc2a0 100644 --- a/docs/DOLT-BACKEND.md +++ b/docs/DOLT-BACKEND.md @@ -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 diff --git a/docs/FAQ.md b/docs/FAQ.md index 7740cd466..bc3f12de0 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -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 ` -- Set `bd config set sync.branch ` +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//` - -**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 diff --git a/docs/GIT_INTEGRATION.md b/docs/GIT_INTEGRATION.md index d65aa8184..3fee722b3 100644 --- a/docs/GIT_INTEGRATION.md +++ b/docs/GIT_INTEGRATION.md @@ -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 diff --git a/docs/PROTECTED_BRANCHES.md b/docs/PROTECTED_BRANCHES.md index 5b77d0c34..6a7ff24e6 100644 --- a/docs/PROTECTED_BRANCHES.md +++ b/docs/PROTECTED_BRANCHES.md @@ -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 +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 diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index fc08ab3d6..3d279d470 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -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 diff --git a/docs/WORKTREES.md b/docs/WORKTREES.md index c63b80c3b..d27f64ae6 100644 --- a/docs/WORKTREES.md +++ b/docs/WORKTREES.md @@ -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 ` or `bd config set sync.branch `), 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 `), 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. diff --git a/examples/protected-branch/README.md b/examples/protected-branch/README.md index 51594353a..8ed0284fd 100644 --- a/examples/protected-branch/README.md +++ b/examples/protected-branch/README.md @@ -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 diff --git a/examples/team-workflow/README.md b/examples/team-workflow/README.md index 892b8682d..2f112162b 100644 --- a/examples/team-workflow/README.md +++ b/examples/team-workflow/README.md @@ -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: diff --git a/integrations/junie/README.md b/integrations/junie/README.md index f6ea2f70b..8088023a3 100644 --- a/integrations/junie/README.md +++ b/integrations/junie/README.md @@ -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 diff --git a/npm-package/CLAUDE_CODE_WEB.md b/npm-package/CLAUDE_CODE_WEB.md index a54ac25a4..2fea159d5 100644 --- a/npm-package/CLAUDE_CODE_WEB.md +++ b/npm-package/CLAUDE_CODE_WEB.md @@ -305,7 +305,7 @@ While working: When done: - Close the issue: `bd close --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 diff --git a/npm-package/INTEGRATION_GUIDE.md b/npm-package/INTEGRATION_GUIDE.md index 001b852ca..556d979aa 100644 --- a/npm-package/INTEGRATION_GUIDE.md +++ b/npm-package/INTEGRATION_GUIDE.md @@ -99,7 +99,7 @@ bd dep tree 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 --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 ` 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 diff --git a/scripts/check-doc-flags.sh b/scripts/check-doc-flags.sh new file mode 100755 index 000000000..aaf1c1898 --- /dev/null +++ b/scripts/check-doc-flags.sh @@ -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 --` 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 diff --git a/website/docs/architecture/index.md b/website/docs/architecture/index.md index 4f5800845..5cfa03ef5 100644 --- a/website/docs/architecture/index.md +++ b/website/docs/architecture/index.md @@ -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 diff --git a/website/docs/cli-reference/essential.md b/website/docs/cli-reference/essential.md index 053230d1e..6d228f126 100644 --- a/website/docs/cli-reference/essential.md +++ b/website/docs/cli-reference/essential.md @@ -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 diff --git a/website/docs/cli-reference/index.md b/website/docs/cli-reference/index.md index 9204d1331..fc22da4c1 100644 --- a/website/docs/cli-reference/index.md +++ b/website/docs/cli-reference/index.md @@ -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 diff --git a/website/docs/cli-reference/sync.md b/website/docs/cli-reference/sync.md index 1d0afdf24..cd13e7c18 100644 --- a/website/docs/cli-reference/sync.md +++ b/website/docs/cli-reference/sync.md @@ -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 [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 diff --git a/website/docs/core-concepts/hash-ids.md b/website/docs/core-concepts/hash-ids.md index 885d3f28b..5bdefe9d3 100644 --- a/website/docs/core-concepts/hash-ids.md +++ b/website/docs/core-concepts/hash-ids.md @@ -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' diff --git a/website/docs/getting-started/ide-setup.md b/website/docs/getting-started/ide-setup.md index 3898749bb..5e175ecda 100644 --- a/website/docs/getting-started/ide-setup.md +++ b/website/docs/getting-started/ide-setup.md @@ -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"] } } ``` diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md index 43ff3e086..047affa38 100644 --- a/website/docs/getting-started/quickstart.md +++ b/website/docs/getting-started/quickstart.md @@ -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: diff --git a/website/docs/getting-started/upgrading.md b/website/docs/getting-started/upgrading.md index bcb124f0b..4719fb22b 100644 --- a/website/docs/getting-started/upgrading.md +++ b/website/docs/getting-started/upgrading.md @@ -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 ``` diff --git a/website/docs/integrations/aider.md b/website/docs/integrations/aider.md index 99104c785..cd16100c9 100644 --- a/website/docs/integrations/aider.md +++ b/website/docs/integrations/aider.md @@ -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 diff --git a/website/docs/integrations/claude-code.md b/website/docs/integrations/claude-code.md index 2dc166f2a..137b7f440 100644 --- a/website/docs/integrations/claude-code.md +++ b/website/docs/integrations/claude-code.md @@ -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 diff --git a/website/docs/integrations/github-copilot.md b/website/docs/integrations/github-copilot.md index 5d954baa4..bfc85c9fd 100644 --- a/website/docs/integrations/github-copilot.md +++ b/website/docs/integrations/github-copilot.md @@ -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 ` - 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 diff --git a/website/docs/integrations/junie.md b/website/docs/integrations/junie.md index 0f9808009..eb74bd063 100644 --- a/website/docs/integrations/junie.md +++ b/website/docs/integrations/junie.md @@ -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 diff --git a/website/docs/intro.md b/website/docs/intro.md index 8247a8cfa..9746dff80 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -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. diff --git a/website/docs/recovery/index.md b/website/docs/recovery/index.md index f52899bed..6e6225808 100644 --- a/website/docs/recovery/index.md +++ b/website/docs/recovery/index.md @@ -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 diff --git a/website/docs/reference/advanced.md b/website/docs/reference/advanced.md index 743be0fb6..b18f5d6aa 100644 --- a/website/docs/reference/advanced.md +++ b/website/docs/reference/advanced.md @@ -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 diff --git a/website/docs/reference/configuration.md b/website/docs/reference/configuration.md index afb1863d3..f185136c7 100644 --- a/website/docs/reference/configuration.md +++ b/website/docs/reference/configuration.md @@ -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 diff --git a/website/docs/reference/faq.md b/website/docs/reference/faq.md index c00e2977a..5c0071fc1 100644 --- a/website/docs/reference/faq.md +++ b/website/docs/reference/faq.md @@ -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 diff --git a/website/docs/reference/git-integration.md b/website/docs/reference/git-integration.md index 751e1d251..5b8b19ef5 100644 --- a/website/docs/reference/git-integration.md +++ b/website/docs/reference/git-integration.md @@ -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** diff --git a/website/docs/reference/troubleshooting.md b/website/docs/reference/troubleshooting.md index d4f616fb2..fc5c653f3 100644 --- a/website/docs/reference/troubleshooting.md +++ b/website/docs/reference/troubleshooting.md @@ -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