* fix(init): wire git origin as Dolt remote Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync. Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only. _codex-gpt-5-xhigh on behalf of maphew_ * test: keep embedded command stderr out of parsed stdout Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_ --------- Co-authored-by: CI Bot <ci@beads.test>
2.3 KiB
2.3 KiB
| id | title | sidebar_position |
|---|---|---|
| git-integration | Git Integration | 2 |
Git Integration
How beads integrates with git.
Overview
Beads uses git for:
- Project hosting - Your code repository also hosts beads configuration
- Hooks - Auto-sync on git operations
Data storage and sync are handled by Dolt (a version-controlled SQL database).
File Structure
.beads/
├── config.yaml # Project config (git-tracked)
├── metadata.json # Backend metadata (git-tracked)
└── dolt/ # Dolt database and server data (gitignored)
Git Hooks
Installation
bd hooks install
Installs:
- pre-commit - Triggers Dolt commit
- post-merge - Triggers Dolt sync after pull
- pre-push - Ensures Dolt sync before push
Status
bd hooks status
Uninstall
bd hooks uninstall
Conflict Resolution
Dolt handles merge conflicts at the database level using its built-in merge capabilities. When conflicts arise during sync, Dolt identifies conflicting rows and allows resolution through SQL.
# Check for and fix conflicts
bd doctor --fix
Protected Branches
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. On new projects with a git origin, bd init configures that origin as the Dolt remote automatically.
Git Worktrees
Beads works in git worktrees using embedded mode:
# In worktree — just run commands directly
bd create "Task"
bd list
Branch Workflows
Feature Branch
git checkout -b feature-x
bd create "Feature X" -t feature
# Work...
bd dolt push
git push
Fork Workflow
# In fork
bd init --contributor
# Work in separate planning repo...
bd dolt push
Team Workflow
bd init --team
# All team members share the Dolt database
bd dolt pull # Pull latest changes from Dolt remote
bd dolt push # Push your changes to Dolt remote
Duplicate Detection
After merging branches:
bd duplicates --auto-merge
Best Practices
- Install hooks -
bd hooks install - Push regularly -
bd dolt pushat session end - Pull before work -
bd dolt pullto get latest issues - Worktrees use embedded mode automatically