Skip to main content
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. Startup config discovery — the rev-parse probe in internal/config’s gitDirsForRepo, which locates a linked worktree’s shared .beads config — scrubs inherited Git routing variables such as GIT_DIR and GIT_WORK_TREE from its subprocess environment whenever it runs, so a routed environment cannot point that one lookup at another repository. The scrub is unconditional for that probe, but the probe is a fallback, not a per-command step: it runs only when nothing earlier in startup has already resolved a config path (internal/config/config.go), so an ancestor .beads/config.yaml or an explicit BEADS_DIR short-circuits it. It is a single probe, not a general guarantee: other startup Git probes still honor inherited routing, including internal/git’s process-cached repository context backing repository-root and hooks-directory lookups and the .beads database discovery probes in internal/beads, so those variables can still select which workspace bd opens. Scrubbing also drops any inherited GIT_CEILING_DIRECTORIES, which widens upward discovery rather than narrowing it: the explicit working directory fixes where that probe’s search starts, not where it stops, so the probe can select a containing parent repository above that directory. Clearing those variables from the bd process environment applies only to bd worktree commands. GIT_CEILING_DIRECTORIES is scrubbed along with the redirects. That removes a bound rather than a redirect, so discovery from the working directory is widened, not narrowed: run in a directory that is not itself a repository, bd can select a containing parent repository that an inherited ceiling would have hidden.
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:
Create linked worktrees normally:
Sync issue data through the configured Dolt remote:

​
External Beads Workspace

If you want a separate issue-tracker repository shared by many code worktrees, point BEADS_DIR at that workspace:
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:

​
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:
If old config still contains a sync branch, clear it:

​
Troubleshooting

​
Database Not Found In A Worktree

Check that the main repository has a .beads directory and that the worktree belongs to that repository:
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