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/.
122 lines
2.9 KiB
Markdown
122 lines
2.9 KiB
Markdown
---
|
|
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:
|
|
|
|
```bash
|
|
bd init
|
|
```
|
|
|
|
Commit the small tracked configuration files if your project policy requires
|
|
them:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`, and `bd close` do not create commits on `main`.
|
|
- `bd dolt push` pushes Dolt data, not a code branch.
|
|
- Normal code changes still go through your existing pull-request workflow.
|
|
|
|
## Team Usage
|
|
|
|
For a shared tracker:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
bd config set sync.branch ""
|
|
```
|
|
|
|
If stale hidden worktrees prevent branch checkout, remove them and prune Git's
|
|
worktree registry:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
bd vc merge <branch> --strategy [ours|theirs]
|
|
bd doctor --fix
|
|
```
|
|
|
|
### Stale Hooks Mention Legacy Sync Commands
|
|
|
|
Refresh generated hooks:
|
|
|
|
```bash
|
|
bd hooks install
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [WORKTREES.md](/reference/worktrees) - Git worktree behavior
|
|
- [GIT_INTEGRATION.md](/reference/git-integration) - general Git integration guide
|
|
- [RECOVERY.md](/recovery/init-safety) - recovery playbooks
|