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/.
3.3 KiB
| title |
|---|
| Git Worktrees Guide |
Beads works from normal Git worktrees without a separate sync branch. Current
beads stores issue data in Dolt under refs/dolt/data, so issue sync is
separate from Git branch commits.
Current Model
All worktrees in the same repository use the same beads workspace unless you
override discovery with BEADS_DIR.
project/
├── .git/ # Shared Git directory
├── .beads/ # Shared beads config and local Dolt data
├── main-worktree/
└── feature-worktree/
Key points:
bddiscovers the repository's.beadsdirectory from linked worktrees.- Issue changes are stored in Dolt, not committed to the current Git branch.
- Cross-clone sync uses
bd dolt pullandbd dolt push. - No
sync.branchor beads-managed Git worktree is required.
Basic Usage
Initialize beads once in the repository:
cd project
bd init
Create linked worktrees normally:
git worktree add ../project-feature feature-branch
cd ../project-feature
bd ready
bd create "Implement feature X" -t feature -p 1
Sync issue data through the configured Dolt remote:
bd dolt pull
bd dolt push
External Beads Workspace
If you want a separate issue-tracker repository shared by many code worktrees,
point BEADS_DIR at that workspace:
export BEADS_DIR=~/project-beads/.beads
cd ~/project/main && bd list
cd ~/project/feature-1 && bd list
cd ~/project/feature-2 && bd list
With an external BEADS_DIR, bd dolt push and bd dolt pull target the
external beads workspace, not the code repository.
Hooks
Git hooks installed by beads are worktree-aware. If hooks are stale or mention removed legacy sync commands, refresh them:
bd hooks install
Legacy Cleanup
Older beads versions had an experimental sync.branch workflow that created
hidden worktrees such as .git/beads-worktrees/<branch>/. That workflow has
been removed.
If a legacy checkout cannot switch branches because a beads-created worktree still holds the branch, remove the stale worktree records:
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune
If old config still contains a sync branch, clear it:
bd config set sync.branch ""
Troubleshooting
Database Not Found In A Worktree
Check that the main repository has a .beads directory and that the worktree
belongs to that repository:
git worktree list
cd /path/to/main/repo
ls -la .beads
If the repository has no beads workspace yet, run bd init from the main
repository.
Multiple .beads Directories
If a worktree has its own accidental .beads directory, remove or archive the
extra copy after confirming it does not contain unique issue data. By default,
worktrees should share the repository workspace.
Concurrent Writers
For ordinary single-user worktree use, run commands directly. For true
multi-writer workflows across machines or agents, sync frequently with
bd dolt pull and bd dolt push, and coordinate through the tracker to avoid
working the same issue concurrently.
See Also
- PROTECTED_BRANCHES.md - protected branch behavior
- GIT_INTEGRATION.md - general Git integration guide
- MULTI_REPO_MIGRATION.md - multi-workspace patterns