beads/docs/reference/protected-branches.md
Chris Sells 69e33099b8 docs: apply PR #4722 review feedback to user docs
- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
  IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
  correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
  body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
  route spaces (1.0.0, 1.0.4, 1.0.5)
2026-07-12 11:06:57 -07:00

123 lines
3.1 KiB
Markdown

---
title: Protected Branches
description: Why beads needs no protected-branch workaround since Dolt stores issue data outside Git refs, plus team workflow and legacy sync-branch cleanup.
---
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
- [Git Worktrees Guide](/reference/worktrees) - Git worktree behavior
- [Git Integration](/reference/git-integration) - general Git integration guide
- [Recovery Playbooks](/recovery/init-safety) - recovery playbooks