mirror of
https://github.com/gastownhall/beads.git
synced 2026-09-14 20:17:24 +08:00
Chris Sells
69e33099b8
- 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)
135 lines
3.5 KiB
Markdown
135 lines
3.5 KiB
Markdown
---
|
|
title: Git Worktrees Guide
|
|
description: Using beads from Git worktrees, which share one .beads workspace, plus external BEADS_DIR setups and legacy sync-branch cleanup.
|
|
---
|
|
|
|
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:
|
|
|
|
- `bd` discovers the repository's `.beads` directory from linked worktrees.
|
|
- Issue changes are stored in Dolt, not committed to the current Git branch.
|
|
- Cross-clone sync uses `bd dolt pull` and `bd dolt push`.
|
|
- No `sync.branch` or beads-managed Git worktree is required.
|
|
|
|
## Basic Usage
|
|
|
|
Initialize beads once in the repository:
|
|
|
|
```bash
|
|
cd project
|
|
bd init
|
|
```
|
|
|
|
Create linked worktrees normally:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
rm -rf .git/beads-worktrees
|
|
rm -rf .git/worktrees/beads-*
|
|
git worktree prune
|
|
```
|
|
|
|
If old config still contains a sync branch, clear it:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](/reference/protected-branches) - protected branch behavior
|
|
- [Git Integration](/reference/git-integration) - general Git integration guide
|
|
- [Multi-Repo Migration Guide](/multi-agent/multi-repo-migration) - multi-workspace patterns
|