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:
commit
e42d222bae
45 changed files with 484 additions and 384 deletions
18
.github/workflows/ci.yml
vendored
18
.github/workflows/ci.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
5
Makefile
5
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"
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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**
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
14
docs/FAQ.md
14
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 <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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
178
scripts/check-doc-flags.sh
Executable 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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
|
|
|
|||
|
|
@ -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"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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**
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue