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.9 KiB
| title |
|---|
| Protected Branches |
Beads does not need a protected-branch workaround in current releases.
Issue data is stored in Dolt under refs/dolt/data, separate from normal Git
branches such as main. Beads commands do not commit issue updates to your
current code branch, so GitHub, GitLab, and Bitbucket branch protection rules
continue to apply only to your code history.
Current Workflow
Initialize beads in the project:
bd init
Commit the small tracked configuration files if your project policy requires them:
git add .beads/.gitignore .beads/metadata.json .beads/config.yaml .gitignore
git commit -m "Initialize beads issue tracker"
The local Dolt database directory remains gitignored. Sync issue data through a Dolt remote:
bd dolt pull
bd dolt push
No beads-sync Git branch, protected-branch exception, or beads-managed Git
worktree is required.
Why Protected Branches Are Safe
Protected branches guard Git refs such as refs/heads/main. Dolt stores beads
data in its own ref namespace. That means:
bd create,bd update, andbd closedo not create commits onmain.bd dolt pushpushes Dolt data, not a code branch.- Normal code changes still go through your existing pull-request workflow.
Team Usage
For a shared tracker:
bd init --team
bd dolt pull
bd ready
bd update <id> --claim
bd dolt push
Pull before starting work and push before handing off so other clones see the latest issue state.
Legacy Sync-Branch Cleanup
Older beads versions documented an experimental sync.branch workflow that
committed .beads changes to a branch such as beads-sync and used hidden Git
worktrees under .git/beads-worktrees/. That workflow has been removed.
If an old checkout still has sync-branch config, clear it:
bd config set sync.branch ""
If stale hidden worktrees prevent branch checkout, remove them and prune Git's worktree registry:
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune
If a remote beads-sync branch exists only for the removed workflow, archive or
delete it according to your repository policy after confirming all current issue
data has been synced through Dolt.
Troubleshooting
bd dolt push Has No Remote
Add or inspect the Dolt remote:
bd dolt remote list
bd dolt remote add origin <remote-url>
bd dolt push
Conflicts During bd dolt pull
Dolt reports database-level conflicts separately from Git branch conflicts. Use the merge strategy or doctor guidance printed by the failed command:
bd vc merge <branch> --strategy [ours|theirs]
bd doctor --fix
Stale Hooks Mention Legacy Sync Commands
Refresh generated hooks:
bd hooks install
See Also
- WORKTREES.md - Git worktree behavior
- GIT_INTEGRATION.md - general Git integration guide
- RECOVERY.md - recovery playbooks