beads/docs/reference/protected-branches.md
Chris Sells a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
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/.
2026-07-12 10:37:07 -07:00

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