Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2.6 KiB
| title |
|---|
| 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 does not conflict with protected Git branches, and no separate
beads-sync branch or protected-branch exception 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 without extra setup. Linked worktrees discover the
repository's .beads workspace and sync issue data through Dolt:
# In a linked worktree
bd create "Task"
bd list
bd dolt pull
bd dolt push
Older beads versions documented a sync.branch workflow that created hidden
Git worktrees. That workflow has been removed; current sync uses Dolt remotes.
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 - Use normal Git worktrees - no sync branch is required