* 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(git): isolate domain role configuration from inherited routing (saa-cgh.109.5) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init): probe the selected repository before configuring roles (saa-cgh.109.8) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * docs(init): explain role probe discovery ceiling behavior (saa-cgh.109.8) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init): bind proxied tail Git operations to selected directory (saa-cgh.109.14) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(gitignore): preserve CRLF when appending project rules (saa-cgh.96) Reported by bee-ghosttrack in gastownhall/beads#6343. Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * test(gitignore): pin detector edge cases and clarify append behavior (saa-cgh.96) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(gitignore): preserve line endings in Git exclude appends (saa-cgh.104) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * test(gitignore): clarify exclude fixture path variable (saa-cgh.104) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(gitignore): refuse exclude writes after read errors (saa-cgh.110) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * refactor(gitignore): share append byte composition (saa-cgh.105) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * docs(gitignore): explain append aliasing and trailing CR completion (saa-cgh.105) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * refactor(gitignore): use shared composition for exclude rules (saa-cgh.111) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(gitignore): omit the empty exclude leading separator (saa-cgh.112) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init): bind exclude writers to the selected Git directory (saa-cgh.109.16) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(hooks): isolate tracked-file guard from Git routing (saa-cgh.98) Follow-up to bee-ghosttrack's review of gastownhall/beads#6322; refs #6356. Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(hooks): retain legitimate inherited tracking context (saa-cgh.98) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * test(hooks): isolate trusted global configuration fixture (saa-cgh.98) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * docs(hooks): explain conservative tracked-file guard (saa-cgh.98) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * refactor(git): resolve hooks paths in an explicit read-only context (saa-cgh.109.17.1) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * Bind init hook operations to the selected repository (saa-cgh.109.17) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * Give the hooks tail fixture an explicit remote context (saa-cgh.109.17) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * test(git): canonicalize the hooks fixture repository root (saa-cgh.109.17.1) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(init): complete selected hook options and alias handling (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * Clarify hooks resolver ownership and preserve work-tree diagnostics (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * Explain restoration of absent routing variables in selected exclude tests (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * Keep init role operations on the captured selected Git context (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * Align selected-tail fixtures with captured role authority (saa-cgh.120) Agent-Signature: Codex-unknown-model-unknown-reasoning on behalf of Ewen Cuthiell * Identify the Git index behind tracked-hook refusals (saa-cgh.120.13) Agent-Signature: unknown-model/unknown-reasoning on behalf of Ewen Cuthiell * fix(review): repair work-tree-less hook install and the fail-open secret guard Maintainer adoption-review fixes for #6457 (iterations 1 and 2). Blocking: - cmd/bd, internal/git: `bd init` in a repository with no work tree stopped installing hooks and printed "Failed to resolve git hooks". git.ResolveHooksContext requires a work tree and deliberately errors without one, so routing the selected-init path through it lost a capability base had via beads.FindBeadsDir(). Add git.ResolveWorkTreelessHooksContext as the explicit counterpart (empty RepoRoot/MainRepoRoot, relative core.hooksPath anchored to the common directory) and fall back to it, so the install keeps the selected, scrubbed context rather than the inherited one. It keys on "the common directory resolved but the work tree did not", so it covers a bare repository and a cwd inside a repository's own .git alike, and still refuses non-repositories and directories inside a work tree. The `bare` and `git_dir_cwd` rows in the hooks table test pin both shapes and assert the install lands in the selected storage and configures the selected repository. - internal/config: isGitTracked scrubbed Git routing with no fallback, so in a checkout reachable only through legitimate GIT_DIR/GIT_WORK_TREE routing the probe found no repository at all, the guard concluded "untracked", and `bd config set <secret-key>` wrote the credential into a git-tracked config.yaml where base refused. Give it the same two-probe shape as hooks.gitTrackedFileContextWithEnv, with a legitimate-routing test. - internal/config, internal/gitenv, docs: state the GIT_CEILING_DIRECTORIES widening plainly rather than pairing it with a containment clause that is false at every live call site. `-C`/cmd.Dir fixes where discovery starts, not where it stops, so with the ceiling scrubbed the walk can reach a containing repository above cwd; all three gitDirsForRepo call sites pass the process working directory, which need not be a repository root. This mirrors the wording init_proxied_server.go already had, so the tree no longer holds contradictory statements about the same primitive. - cmd/bd/config.go: the policy comment claimed all role commands ignore inherited Git routing. Name the scrubbed paths without asserting a closed set -- `bd config set/get/unset/set-many beads.role`, and the proxied-init role tail, which goes through domain.GitUseCase.BeadsRole/SetBeadsRole and is scrubbed on both of that repository's constructor arms -- and say that a path which does not scrub still goes through the inherited environment: such readers include internal/routing.roleFromGitConfig, RepoContext.Role, doctor.CheckBeadsRole, `bd config show` and init.getBeadsRole; such writers include init.setBeadsRole, `bd init --contributor` and `bd hooks --uninstall`. The earlier wording framed the exception as role *resolution* only, which reads as isolating the write plane when it is not isolated; a quantifier over "every other" reader and writer goes stale in the opposite direction, since set-many and the proxied-init tail are scrubbed, so neither list is exhaustive here. Non-blocking: - Scope the worktrees.md paragraph to the one startup probe that is scrubbed. - Replace normalizeWorktreeGitEnvKey's ToUpper fold with execenv.KeyEqualForOS so one subprocess key identity survives the PR. - Compare beads.role against domain.BeadsRoleConfigKey with strings.ToLower rather than strings.EqualFold, matching execenv.keyIdentityForWindows and git's ASCII-only key folding, and pin it with Beads.Role/BEADS.ROLE rows through GetConfig/SetConfig. - Share the HooksContext workDir anchoring and symlink/case normalization between both resolvers, so no producer of that type emits a spelling the others do not. - Branch the tracked-hook remediation hint on the proof label, so the inherited case points at the routing rather than at `git rm --cached`. - Restore the hook-status gate on the pure-JJ alias hint (base parity). - Note that the boolean tracked-file wrappers are test-only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(review): reconcile the beads.role scrub with base #6477 on the refreshed base Refreshing onto main511849496pulled incf683435e(#6477), which makes domain/git GetConfig propagate Git's exit error instead of mapping every *exec.ExitError to absence. That collides with this stack's beads.role scrub in both directions, and neither lane's CI could see it: the PR lane builds against a base where #6477's test does not exist, and main's lane never has the PR. Only the merged tree fails (each half passes on its own side alone). The test half is taken byte-identically from stack parent #6464, which already pushed this resolution against the same base commit (head0fe936944). Both PRs target main with every parent still open, so a divergent-but-equivalent fix here would collide in the same file when the stack lands; copying theirs means the two auto-merge. Re-validated and re-mutation-proven here rather than assumed: - TestConfig_ReadFailuresAreNotMissing drops its "invalid_routing_boolean" row, whose poisoned GIT_CONFIG_NOSYSTEM can no longer reach git for beads.role (IsRoutingKeyForOS scrubs the whole GIT_CONFIG* prefix for that key), and gains TestConfig_BeadsRoleScrubsInheritedRoutingEnv, which pins both halves: the role key ignores the poison, and a key outside the scrub (user.name) still surfaces it as exit 128 rather than as an absent key. #6477's read-failure contract for beads.role itself is untouched, still proved by malformed_config through the repository's own config file. - TestInitGitRepositoryUsesSelectedDirectory/captured_home asserted require.NoError with the comment "The existing reader maps Git exit errors to absence" -- the premise #6477 deleted. It now requires the exit-128 error, which is itself the proof that the generic constructor read the *current* caller environment: only that environment can see the planted .gitconfig. Mutation proofs at this head: deleting the beads.role carve-out reds TestConfig_BeadsRoleScrubsInheritedRoutingEnv; reverting #6477's classification reds both that test and captured_home. So neither retargeted fixture is vacuous. Also silence two gosec G702 findings that only appear with this branch present. Unscoped `make ci-pr-lint` at CI's v2.10.1 pin scores 0 on the old base and 0 on current main, 1 on the pre-refresh adopted head (cmd/bd/worktree.go:22) and 2 on the refreshed head (+ cmd/bd/hooks.go:1823). pr.yml scopes golangci-lint to the PR's own diff so it can never report them, but main.yml deliberately sweeps the whole tree, so they would red main's Lint job on the first push after merge. Production reachability is identical on all three trees, so this is taint widening rather than a new call path. Both sinks run a fixed "git" binary with constant subcommands, matching the justification at init_stealth.go:84. cmd/bd/worktree.go is the only file this adds beyond the branch's own 50; #6464 does not touch it, so the annotation cannot collide with the parent either. --------- Signed-off-by: Ewen Cuthiell <ewencuthiell@gmail.com> Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
159 lines
5.1 KiB
Markdown
159 lines
5.1 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`.
|
|
|
|
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.
|
|
|
|
```
|
|
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
|