Beads 与 Git Worktree 协同指南共享 .beads 工作区、BEADS_DIR 外部工作区与遗留同步分支清理【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeadsbd命令可以在普通 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/databootstrap.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其解析顺序为BEADS_DIR环境变量最高优先级先检查环境变量指定的目录跟随可能的 redirect 文件后验证其中是否含有真实的项目文件从 CWD 向上走查从当前目录逐级向上寻找.beads/目录。对 worktree 而言走查在 worktree root 处停止不检查 worktree root 自身的.beads/避免命中那些只有被 git 跟踪的元数据、却没有数据库的继承目录worktree 专属 fallbackper-worktree redirect、worktree 自己的.beadsseparate-DB 模式、或通过git-common-dir找到共享.beads扩展走查从 worktree root 边界继续向上走到主仓库根目录。判断一个目录是否算数由hasBeadsProjectFiles把关只有包含metadata.json、config.yaml、dolt/、embeddeddolt/目录或非备份的*.db文件才被认定为有效工作区见 beads.go。配套的严格判断hasBeadsDatabase用于区分真正拥有独立 Dolt 数据的 worktree与通过 git checkout 继承了被跟踪的.beads/元数据、但数据库在共享处的 worktreebeads.go。值得注意的边界情况都有对应回归测试worktree root 可能包含被 git 跟踪的.beads元数据如config.yaml而没有数据库此时会优先回退到共享的 worktree 数据库beads_test.go类似地jj 的 secondary workspace 也会走 worktree 同款 fallbackbeads.go路径规范化CanonicalizePath保证 macOS 上/var与/private/var这类符号链接差异不会破坏边界判断beads.go。基本用法在 worktree 中初始化与操作 issue先在仓库中初始化一次 beadscd 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 中。Hooksworktree 感知的 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 staginghooks.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考