* fix(worktree): scrub inherited Git routing state Establish CWD as the worktree repository boundary before discovery can consume inherited Git routing. Fence the startup config probe, clear routing in-process before root pre-run discovery, and retain command-owned subprocess scrubbing as defense in depth without changing PID or signal semantics. Fixes #5531 Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell * refactor(worktree): explain owned filtering and remove an unused shim Document why filtering the fresh routing slice in place is safe and call the shared routing-key classifier directly from tests. Retain the two forwarders used by production worktree subprocess/removal paths. Review: https://github.com/gastownhall/beads/pull/5623#pullrequestreview-5098421671 Bead: saa-cgh.23 Agent-Signature: unknown-model/unknown-reasoning * fix(config): isolate identity and tracked-file Git probes from routing Reuse the worktree routing owner for GetIdentity and isGitTracked so explicit cwd/path selection is not displaced by inherited repository, index or injected config state. Preserve identity precedence and the tracked-secret refusal contract, with real target/decoy regressions. Follow-up: https://github.com/gastownhall/beads/issues/6222 Dependency: https://github.com/gastownhall/beads/pull/5623 Reported-by: bee-ghosttrack Bead: saa-cgh.93 Agent-Signature: unknown-model/unknown-reasoning * fix(config): share subprocess key identity for Git routing (saa-cgh.93) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(exec): match Windows environment key identity (#5618) Centralize os/exec-compatible environment-key comparison and use it for credential, metrics, Git-hook, trace, and repro subprocess filters. Preserve exact Unix semantics and Unicode near-collisions. Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Ewen Cuthiell Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com> * test(execenv): exercise every environment operation under both host rules Thread the host choice through narrow private helpers behind the existing exported functions. Keep one normalization owner and retain native wrapper tests; the additional table covers both host branches for equality, prefix matching, last-wins lookup, filtering and input preservation. Review: https://github.com/gastownhall/beads/pull/5672#pullrequestreview-5096948965 Bead: saa-cgh.78 Agent-Signature: unknown-model/unknown-reasoning * test(execenv): exercise exported host policy wiring (saa-cgh.78) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * docs(worktree): explain startup Git environment scope (saa-cgh.23) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(config): isolate role commands from Git routing (saa-cgh.99) Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6357. Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * test(env): exercise shared key helpers on native Windows (saa-cgh.78) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * refactor(gitenv): share key parsing and normalize routing membership once (saa-cgh.93) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * docs(config): explain role command routing policy (saa-cgh.99) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init): isolate role configuration from inherited Git routing (saa-cgh.109.3) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init): use the selected origin in contributor setup (saa-cgh.109.7) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init): isolate Git writes in planning repositories (saa-cgh.109.9) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * test(init): retain inherited planning commit author (saa-cgh.109.9) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init): align embedded role gates with selected Git context (saa-cgh.109.12) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init): scope embedded artifact Git operations to selected directory (saa-cgh.109.15) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * test(init): cover selected optional artifacts and explain refused commits (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * Honor role-probe cancellation and exercise actual fork planning (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * fix(init): warn when automatic contributor role write fails (saa-cgh.109.3) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * test(init): cover successful nonquiet contributor role writes (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * Assert the automatic contributor setup banner alongside warnings (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * test(init): read persisted role routing from the store (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * Bind early embedded Git bootstrap to the selected project (saa-cgh.120.9) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * Create the owned separate-storage parent in the bootstrap fixture (saa-cgh.120.9) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init,gitenv,config): maintainer fixup for #6459 Review iteration 1, blocking: - cmd/bd/init_stealth.go: scope the fork exclude writer the way this PR scoped the fork detector. detectForkSetup now scrubs inherited Git routing, but resolveGitExcludePath still ran `git rev-parse --git-common-dir` with no Dir and no Env, so with GIT_DIR inherited toward another repository bd detected the fork in the selected repo and then appended `.beads/`, `**/RECOVERY*.md` and `**/SESSION*.md` to the *inherited* repository's .git/info/exclude - automatically, with no prompt, in non-interactive mode. At base the two halves agreed (both saw the inherited repo, found no upstream, wrote nothing), so the PR is what creates the disagreement. Scrubbing the probe is the whole remedy: no cmd/bd caller chdirs, so `repoPath == ""` already means the selected project directory once inherited routing is gone. The new test asserts both halves - the selected repo is written, the inherited one is byte-unchanged - and reverting the scrub reds it while every existing exclude test stays green. - cmd/bd/config.go: the new comment claimed "All role commands ignore inherited Git routing". Only bd config's own role paths were hardened - routing.DetectUserRole, `bd config show`, `bd doctor` and `bd hooks uninstall` still resolve beads.role through the inherited environment, and beads.RepoContext.Role pins GIT_DIR/GIT_WORK_TREE last-wins but still inherits GIT_CONFIG_*. So `bd config get beads.role` and `bd config show` can disagree in one shell, and `bd config unset beads.role` and `bd hooks uninstall` can target different repositories. Narrow the comment to the command set it covers; widening the boundary to the deciders is a separate, permissions-adjacent change. The same root cause is filed on #6460 and #6464, where it is broader - fix it once, on whichever merges first. Review iteration 1, non-blocking: - docs/reference/worktrees.md: the new prose claimed startup Git discovery probes for every bd command scrub inherited routing. Only internal/config's gitDirsForRepo does; internal/git's process-cached context does not. Narrow the sentence to config discovery and name both sides. - internal/gitenv/routing.go: say in the contract comment why GIT_CEILING_DIRECTORIES is a routing key even though it narrows rather than redirects, and disclose that removing it widens the upward search. Pin the membership with a ceiling entry in the existing scrub table. - cmd/bd/worktree_cmd.go: route the removal pass's key identity through execenv.KeyIdentityForOS instead of the last hand-rolled fold. ToUpper is the opposite direction from the shared primitive and provably non-equivalent: on Windows it collapsed GıT_OPTIONAL_LOCKS (U+0131) onto GIT_OPTIONAL_LOCKS and stripped an unrelated variable that gitenv.ScrubRoutingForOS, one line earlier, keeps. Validation: go build ./..., go vet, CGO_ENABLED=0 vet and GOOS=windows CGO_ENABLED=0 vet all clean; internal/gitenv green; cmd/bd filtered run green except TestGetNotionConfigReadsDBPathWhenStoreUnset and TestConfigValidateReadOnlyIsHermetic, which fail identically at the unmodified head. All three new pins mutation-proved. Review iteration 2, non-blocking: - internal/config/worktree_config_test.go, cmd/bd/init_git_bootstrap_routing_test.go: finish the conditional half of iteration 1's GIT_CEILING_DIRECTORIES item. That item offered "drop the key" or "keep it and say so - and if kept, add a legitimate-ceiling case to the two cited tests". The docs arm was taken but only one of the two tests got a case, and the half left unpinned is the widening the new contract comment now promises. Both new cases set a *legitimate* ceiling - an operator fencing off an ancestor - and assert the scrub widens past it: startup config discovery still resolves the main repository's shared config, and `bd init`'s bootstrap probe still resolves the containing repository. Each carries a control that fails the test if the ceiling did not bite, so neither can pass vacuously. Dropping GIT_CEILING_DIRECTORIES from routingKeys reds both new pins while TestWorktreeFallbackConfigPathIgnoresInheritedGitRouting and TestSetupForkExcludeIgnoresInheritedGitRouting stay green, so they cover an arm the poisoned-routing pins do not. The review prescribed this assertion in the inverted direction ("a fenced-off ancestor does not suppress the fresh git init"). Measured against git 2.43.0: a ceiling at a repository root does fence off a probe run from a subdirectory, so scrubbing it makes the ancestor visible and the fresh `git init` is suppressed. The tests pin the measured direction. - cmd/bd/init_stealth.go: the scrub makes resolveGitExcludePath's "not a git repository" newly reachable from `bd init --setup-exclude` exactly where the cause is interesting, but the probe's error was discarded. Thread git's own reason through, reusing firstNonEmptyLine from sync_git.go, which already exists for this failure shape. exec.ExitError.Error() is only "exit status 128", so a bare %w would have added nothing readable. The "not a git repository" prefix is load-bearing - setupStealthMode matches it with strings.Contains to treat this as a skip - and is preserved. Rendered: Warning: failed to configure git exclude: not a git repository (inherited Git routing is ignored here): fatal: not a git repository (or any of the parent directories): .git Validation (iteration 2): gofmt clean; go build ./...; go vet, CGO_ENABLED=0 go vet and GOOS=windows CGO_ENABLED=0 go vet clean on cmd/bd and internal/config. Both new pins green and mutation-proved as described; the nine existing cmd/bd exclude/routing/fold pins, the internal/config worktree-fallback set, and the internal/gitenv and internal/execenv suites all stay green. No production behavior change beyond the error text. --------- Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com> Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com> Co-authored-by: Julian Knutsen <julian@example.com>
4 KiB
| title | description |
|---|---|
| Git Worktrees Guide | 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.
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. Other startup Git probes still honor inherited
routing, including internal/git's process-cached repository context. Clearing
those variables from the bd process environment applies only to bd worktree
commands.
project/
├── .git/ # Shared Git directory
├── .beads/ # Shared beads config and local Dolt data
├── main-worktree/
└── feature-worktree/
Key points:
bddiscovers the repository's.beadsdirectory from linked worktrees.- Issue changes are stored in Dolt, not committed to the current Git branch.
- Cross-clone sync uses
bd dolt pullandbd dolt push. - No
sync.branchor beads-managed Git worktree is required.
Basic Usage
Initialize beads once in the repository:
cd project
bd init
Create linked worktrees normally:
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:
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:
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:
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:
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune
If old config still contains a sync branch, clear it:
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:
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 - protected branch behavior
- Git Integration - general Git integration guide
- Multi-Repo Migration Guide - multi-workspace patterns