企业官网建设流程全解析

Beads 与 Git Worktree 协同指南：共享 .beads 工作区、BEADS_DIR 外部工作区与遗留同步分支清理

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

Beads（bd命令）可以在普通 Git worktree 中直接工作，无需独立的同步分支：当前版本将 issue 数据存储在 Dolt 中并放在refs/dolt/data引用下，因此 issue 同步与 Git 分支提交完全解耦。本文基于 docs/reference/worktrees.md 展开，结合仓库源码说明工作区发现机制、基本用法、外部BEADS_DIR工作区、worktree 感知的 hooks，以及旧版sync.branch工作流的清理与常见故障排查，帮助你在一台机器上并行开多个分支而不丢失任何 issue 数据。

当前模型：所有 worktree 共享同一个 .beads 工作区

在同一仓库中，所有 linked worktree 默认使用同一个 beads 工作区，除非用BEADS_DIR覆盖发现逻辑。目录结构如下：

project/ ├── .git/ # Shared Git directory（共享的 Git 目录） ├── .beads/ # Shared beads config and local Dolt data（共享配置与本地 Dolt 数据） ├── main-worktree/ └── feature-worktree/

几个关键事实：

• bd可以从 linked worktree 中正确发现仓库的.beads目录；
• issue 变更存储在 Dolt 中，而不是提交到当前 Git 分支；
• 跨克隆同步使用bd dolt pull与bd dolt push；
• 不再需要sync.branch，也不需要 beads 管理的 Git worktree。

底层原理：Dolt 数据存在 refs/dolt/data 下

为什么 worktree 场景下不需要同步分支？因为 beads 的 issue 数据并不跟随 Git 分支提交。从源码可以确认，beads 将 Dolt 数据保存在 git 引用refs/dolt/data下，例如 dolt_remote_reset_data.go 中定义了常量gitDoltDataRef = "refs/dolt/data"；bootstrap.go 的文档注释也明确指出"如果 git origin 上有 Dolt 数据（refs/dolt/data）：从 git 克隆并连接 origin 以便后续 push/pull"。

这也意味着：bd dolt push将 issue 数据库推送到 git 远程的refs/dolt/data引用上，bd dolt pull从中拉取，它们与你在 worktree 里检出的代码分支互不干扰。测试 bootstrap_test.go 演示了通过git push origin HEAD:refs/dolt/data建立该引用的完整流程。

底层原理：工作区发现（FindBeadsDir）的解析顺序

bd如何在 worktree 中找到共享的.beads？核心实现位于 internal/beads/beads.go 的FindBeadsDir，其解析顺序为：

1. BEADS_DIR环境变量（最高优先级）：先检查环境变量指定的目录，跟随可能的 redirect 文件后，验证其中是否含有真实的项目文件；
2. 从 CWD 向上走查：从当前目录逐级向上寻找.beads/目录。对 worktree 而言，走查在 worktree root 处停止（不检查 worktree root 自身的.beads/），避免命中那些"只有被 git 跟踪的元数据、却没有数据库"的继承目录；
3. worktree 专属 fallback：per-worktree redirect、worktree 自己的.beads（separate-DB 模式）、或通过git-common-dir找到共享.beads；
4. 扩展走查：从 worktree root 边界继续向上走到主仓库根目录。

判断一个目录是否"算数"由hasBeadsProjectFiles把关：只有包含metadata.json、config.yaml、dolt/、embeddeddolt/目录或非备份的*.db文件才被认定为有效工作区（见 beads.go）。配套的严格判断hasBeadsDatabase用于区分"真正拥有独立 Dolt 数据的 worktree"与"通过 git checkout 继承了被跟踪的.beads/元数据、但数据库在共享处"的 worktree（beads.go）。

值得注意的边界情况（都有对应回归测试）：

• worktree root 可能包含被 git 跟踪的.beads元数据（如config.yaml）而没有数据库，此时会优先回退到共享的 worktree 数据库（beads_test.go）；
• 类似地，jj 的 secondary workspace 也会走 worktree 同款 fallback（beads.go）；
• 路径规范化（CanonicalizePath）保证 macOS 上/var与/private/var这类符号链接差异不会破坏边界判断（beads.go）。

基本用法：在 worktree 中初始化与操作 issue

先在仓库中初始化一次 beads：

cd project bd init

然后正常创建 linked worktree 并开始工作：

git worktree add ../project-feature feature-branch cd ../project-feature bd ready bd create "Implement feature X" -t feature -p 1

通过配置好的 Dolt 远程同步 issue 数据：

bd dolt pull bd dolt push

要点：

• bd init只需在主仓库执行一次，worktree 通过共享.git的 common dir 复用同一工作区；
• bd ready输出当前可领取的任务，bd create用于创建 issue（-t指定类型，-p指定优先级）；所有 issue 数据即时落入共享的 Dolt 数据库，与当前分支无关；
• bd dolt push/bd dolt pull的实现在 cmd/bd/dolt.go 中，push 与 pull 子命令都会在遇到历史分叉时输出分叉指引（printDivergedHistoryGuidance），提示你如何协调多写入方。

外部 Beads 工作区：用 BEADS_DIR 共享一个 issue 跟踪仓库

如果你希望多个代码 worktree 共享一个独立的 issue 跟踪仓库，可以把BEADS_DIR指向那个工作区：

export BEADS_DIR=~/project-beads/.beads cd ~/project/main && bd list cd ~/project/feature-1 && bd list cd ~/project/feature-2 && bd list

使用外部BEADS_DIR时，bd dolt push和bd dolt pull的目标是外部 beads 工作区，而不是代码仓库。

从源码看，这正是FindBeadsDir的第一步——BEADS_DIR优先级高于任何目录走查（beads.go），且路径会被规范化、支持 redirect 跟随、并经过hasBeadsProjectFiles校验。测试中大量使用t.Setenv("BEADS_DIR", ...)来隔离测试工作区（例如 bootstrap_test.go、config_isolation_regression_test.go），这从侧面印证了该环境变量是整个工具链的工作区"总开关"。

适用场景：多个项目（甚至多个仓库）共用一套 issue 池、由多个 agent 或协作者并行处理任务，而代码本身分散在各仓库的 worktree 中。

Hooks：worktree 感知的 Git 钩子

beads 安装的 Git hooks 是 worktree 感知的。若 hooks 过期或仍提及已移除的遗留同步命令，刷新即可：

bd hooks install

源码佐证：hooks 安装在common git dir（即仓库级共享的 hooks 目录，而非某个 worktree 私有目录），见 cmd/bd/hooks.go 的注释"Get hooks directory from common git dir (hooks are shared across worktrees)"，以及 hooks.go 中"使用绝对路径对 git worktree 至关重要（GH#2414）"的说明——因为 worktree 中.git是一个文件而非目录，.beads/hooks在 worktree 中会错误解析为<worktree>/.beads/hooks/，绝对路径规避了这一问题。

此外 hooks 还具备跨 worktree 的 staging 处理：能识别触发 hook 的 worktree，并对.beads/redirect场景（全路径指向外部工作区）正确应用跨 worktree staging（hooks.go）。

遗留清理：移除旧的 sync.branch 工作流

旧版 beads 曾有一个实验性的sync.branch工作流，会在.git/beads-worktrees/<branch>/下创建隐藏 worktree。该工作流已被移除。

如果旧 checkout 因为 beads 创建的 worktree 仍占着分支而无法切换，请删除陈旧的 worktree 记录：

rm -rf .git/beads-worktrees rm -rf .git/worktrees/beads-* git worktree prune

如果旧配置里还残留 sync branch，清空它：

bd config set sync.branch ""

执行清理后，建议再用bd hooks install刷新一次 hooks，确保没有残留的旧同步命令引用。

故障排查

在 worktree 中提示 Database Not Found

先确认主仓库有.beads目录，且该 worktree 确实属于这个仓库：

git worktree list cd /path/to/main/repo ls -la .beads

如果仓库还没有 beads 工作区，在主仓库中运行bd init。注意：bd init应始终从主仓库执行——init.go 会在存在refs/dolt/data时拒绝用新的本地身份覆盖远程数据，避免多仓库身份冲突。

存在多个 .beads 目录

如果某个 worktree 意外带有一个自己的.beads目录，请在确认其中不包含唯一 issue 数据后，移除或归档这份多余副本。默认情况下，worktree 应当共享仓库级工作区。

为什么会"意外"出现多个.beads？从 beads.go 可以看到，beads 支持"worktree 自己拥有独立数据库"的 separate-DB 模式；但若 worktree root 的.beads只是 git checkout 继承的元数据（有metadata.json但没有数据库），FindBeadsDir会特意跳过它、回退到共享数据库，这正是hasBeadsDatabase严格判断存在的意义。

并发写入

• 普通单用户 worktree 场景：直接运行命令即可，无需额外协调；
• 真正的多写入方场景（跨机器、多个 agent）：频繁使用bd dolt pull/bd dolt push同步，并通过 tracker 协调，避免多个写入方同时处理同一个 issue。

bd dolt push/bd dolt pull遇到分叉历史时会打印printDivergedHistoryGuidance指引（dolt.go），这说明 Dolt 的版本化数据库本身具备冲突检测能力，但最佳实践仍是"高频同步 + 任务分片"。

相关文档

• Protected Branches（受保护分支行为）
• Git Integration（通用 Git 集成指南）
• Multi-Repo Migration Guide（多仓库迁移与多工作区模式）

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads