Systematic cleanup of stale documentation references left over from the Dolt migration: - Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files - Replace all 'bd import' → 'bd init --from-jsonl' or remove - Replace 'bd init --branch' → note about refs/dolt/data separation - Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly) - Fix npm-package, claude-plugin, integrations, examples, website docs Add scripts/check-doc-flags.sh to catch stale doc references: - Checks for removed commands (bd sync, bd import) - Checks for removed flags (bd init --branch) - Warns on legacy SQLite/beads.db references - Compares CLI_REFERENCE.md against bd help --all Add CI job (check-doc-flags) and Makefile target (check-docs) to gate PRs against doc freshness. Prior art: feat/help-doc-generator branch has bd help --doc/--list for generating docs FROM CLI output. This script validates docs AGAINST CLI output — complementary approaches. Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6 Co-authored-by: Amp <amp@ampcode.com>
179 lines
3.1 KiB
Markdown
179 lines
3.1 KiB
Markdown
---
|
|
id: sync
|
|
title: Sync & Export
|
|
sidebar_position: 6
|
|
---
|
|
|
|
# Sync & Export Commands
|
|
|
|
Commands for synchronizing with Dolt.
|
|
|
|
## bd dolt push
|
|
|
|
Push changes to a Dolt remote.
|
|
|
|
```bash
|
|
bd dolt push [flags]
|
|
```
|
|
|
|
**What it does:**
|
|
1. Dolt commit (snapshot current database state)
|
|
2. Push commits to Dolt remote
|
|
|
|
**Examples:**
|
|
```bash
|
|
bd dolt push
|
|
```
|
|
|
|
**When to use:**
|
|
- End of work session
|
|
- 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).
|
|
|
|
```bash
|
|
bd export [flags]
|
|
```
|
|
|
|
**Flags:**
|
|
```bash
|
|
--output, -o Output file (default: stdout)
|
|
--dry-run Preview without writing
|
|
--json JSON output
|
|
```
|
|
|
|
**Examples:**
|
|
```bash
|
|
bd export
|
|
bd export -o backup.jsonl
|
|
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 migrate
|
|
|
|
Migrate database schema.
|
|
|
|
```bash
|
|
bd migrate [flags]
|
|
```
|
|
|
|
**Flags:**
|
|
```bash
|
|
--inspect Show migration plan (for agents)
|
|
--dry-run Preview without changes
|
|
--cleanup Remove old files after migration
|
|
--yes Skip confirmation
|
|
--json JSON output
|
|
```
|
|
|
|
**Examples:**
|
|
```bash
|
|
bd migrate --inspect --json
|
|
bd migrate --dry-run
|
|
bd migrate
|
|
bd migrate --cleanup --yes
|
|
```
|
|
|
|
## bd hooks
|
|
|
|
Manage git hooks.
|
|
|
|
```bash
|
|
bd hooks <subcommand> [flags]
|
|
```
|
|
|
|
**Subcommands:**
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `install` | Install git hooks |
|
|
| `uninstall` | Remove git hooks |
|
|
| `status` | Check hook status |
|
|
|
|
**Examples:**
|
|
```bash
|
|
bd hooks install
|
|
bd hooks status
|
|
bd hooks uninstall
|
|
```
|
|
|
|
## Auto-Sync Behavior
|
|
|
|
### With Dolt Server Mode (Default)
|
|
|
|
When the Dolt server is running, sync is handled automatically:
|
|
- Dolt auto-commit tracks changes
|
|
- Dolt-native replication handles remote sync
|
|
|
|
Start the Dolt server with `bd dolt start`.
|
|
|
|
### Embedded Mode (No Server)
|
|
|
|
In CI/CD pipelines and ephemeral environments, no server is needed:
|
|
- Changes written directly to the database
|
|
- Must manually push to remote
|
|
|
|
```bash
|
|
bd create "CI-generated task"
|
|
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 `bd dolt pull`, Dolt identifies
|
|
conflicting rows and allows resolution through SQL.
|
|
|
|
```bash
|
|
# Check for conflicts after pull
|
|
bd doctor --fix
|
|
```
|
|
|
|
## Deletion Tracking
|
|
|
|
Deletions are tracked in the Dolt database:
|
|
|
|
```bash
|
|
# Delete issue
|
|
bd delete bd-42
|
|
|
|
# View deletions
|
|
bd deleted
|
|
bd deleted --since=30d
|
|
|
|
# Deletions propagate via Dolt push
|
|
bd dolt push
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
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
|