beads 的bd worktree命令完全指南让多个编码 Agent 并行开发时共享同一份议题数据库【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd worktree是 beads 中管理 Git worktree工作树的一等公民命令集它让多个工作目录共享同一个 Git 仓库与同一份 beads 议题数据库从而支撑多 Agent 并行开发、多特性分支同时推进的协作模式。本文以bd help --doc worktree生成的 CLI 参考文档 为核心骨架结合命令的源码实现cmd/bd/worktree_cmd.go、cmd/bd/worktree_remove_cmd.go与配套指南docs/reference/worktrees.md完整讲解create/info/list/remove四个子命令的用法、输出格式与底层安全机制读完即可在自己仓库中安全落地一库多工作树的并行开发流程。为什么需要bd worktree并行开发的正确打开方式Git worktree 允许在同一仓库上挂载多个工作目录每个目录检出不同的分支互不干扰。beads 在此基础上解决了一个关键问题这些工作目录应当共享同一份 beads 数据库.beads而不是各自初始化一份孤立的议题数据。每个 worktree 通过 git 的 common directory公共目录发现机制自动定位主仓库的.beads目录——无需手工配置任何 redirect 文件源码说明议题数据存放在 Dolt 中位于refs/dolt/data与 Git 分支提交相互独立因此切换分支不会丢失议题状态docs/reference/worktrees.md跨克隆同步通过bd dolt pull/bd dolt push完成不再需要早期实验性的sync.branch工作流。命令整体结构来自 worktree_cmd.go 的命令注册bd worktree [flags] 子命令 bd worktree create name [--branchbranch] # 创建 worktree bd worktree info [--json] # 查看当前 worktree 信息 bd worktree list [--json] # 列出所有 worktree 及 beads 状态 bd worktree remove name [--force] # 带安全检查移除 worktree一个值得注意的实现细节worktreeCmd携带skipStoreAnnotation: 1注解整个命令子树不会打开 beads 存储源码测试 TestWorktreeCommandNoStoreContract 专门锁定了这一契约保证即便配置了 Dolt server 模式bd worktree系列命令也不会因为仓库存储不可用而失败。bd worktree create创建并行开发工作目录create子命令用于创建 worktree语法与执行流程如下bd worktree create name [--branchbranch] [flags]FlagsFlag类型默认值说明--branchstring与 name 相同为 worktree 指定的分支名注册源码典型用法bd worktree create feature-auth # 在 ./feature-auth 创建 worktree bd worktree create bugfix --branch fix-1 # 使用显式分支名 fix-1 bd worktree create ../agents/worker-1 # 在相对路径创建支持仓库外的目录命令执行步骤对应 runWorktreeCreate 实现解析并校验路径将name转为绝对路径若该路径已存在直接报错path already exists测试 TestWorktreeCreateRejectsInvalidPathBeforeStoreOpen 验证了在打开 store 之前就拒绝非法路径的行为获取仓库上下文调用beads.GetRepoContext()校验.beads存在并解析路径worktree 操作始终使用当前工作目录所在的仓库rc.CWDRepoRoot而非BEADS_DIR指向的仓库确定分支名未指定--branch时取路径 basename 作为分支名执行 git 创建优先执行git worktree add -b branch path若分支已存在-b 失败自动回退为git worktree add path branch检出既有分支洁净性检查通过git status --porcelainv1 --untracked-filesall确认新建 worktree 检出后是干净的若出现脏状态则拒绝继续ensureCreatedWorktreeClean测试 TestEnsureCreatedWorktreeCleanRejectsDirtyWorktree修复.beads权限git worktree 检出可能把被跟踪的.beads/以 0755 等宽松 umask 权限落下这里调用config.FixBeadsDirPermissions将其对齐bd init的标准权限避免 Agent 循环触发权限告警repairWorktreeBeadsPermissions写入.gitignore若 worktree 位于仓库根目录内把相对路径追加到.gitignore非致命操作失败仅告警。其中第 4 步的 git 调用是有安全考量的gitCmdInDir统一追加-c core.hooksPath并清空GIT_TEMPLATE_DIR在纵深防御层面禁用 git hooks 与模板源码注释防止创建 worktree 时触发不可信钩子。.gitignore的追加逻辑也做了防重复设计写入前先用git check-ignore -q --no-index判断该路径是否已被忽略再逐行比对已有条目只有确实未覆盖时才追加# bd worktree\nentry/\naddToGitignore 实现测试 TestAddToGitignore。JSON 输出配合全局--json成功时返回{path: ..., branch: ...}人类可读输出形如✓ Created worktree: /path/to/repo/feature-auth Branch: feature-authbd worktree info查看当前 worktree 状态info子命令报告当前所在目录是否处于 worktree 中及其详细信息bd worktree info [flags]判断逻辑优先使用RepoContext.IsWorktree失败时回退到git.IsWorktree()——后者通过比较--git-dir与--git-common-dir是否一致来判定internal/git/gitdir.go主仓库定位使用git.GetMainRepoRoot()对嵌套 worktree如/project/.worktrees/feature/也能通过--git-common-dir正确返回主仓库根internal/git/gitdir.go。人类可读输出runWorktreeInfo 实现Worktree: /path/to/repo/feature-auth Name: feature-auth Branch: feature-auth Main repo: /path/to/repo Beads: redirects to /shared/beads/.beads # 或被重定向时的目标 Beads: local (no redirect) # 未重定向时不在 worktree 中时输出Not in a git worktree (this is the main repository)。JSON 输出字段bd worktree info --json{ is_worktree: true, path: /path/to/repo/feature-auth, name: feature-auth, branch: feature-auth, main_repo: /path/to/repo, beads_redirected: true, beads_local: /path/to/repo/feature-auth/.beads, beads_target: /shared/beads/.beads }其中beads_redirected/beads_local/beads_target仅在检测到 redirect 时出现未处于 worktree 时 JSON 只返回{is_worktree: false}。bd worktree list一览所有 worktree 的 beads 状态list子命令基于git worktree list --porcelain枚举仓库的全部 worktree并逐一对齐 beads 配置状态runWorktreeList 实现bd worktree list [flags]每个 worktree 显示四类信息Name目录名主仓库显示为(main)、Path完整路径、Branch、Beads 状态。状态由 getBeadsState 依据.beads目录判定语义如下Beads 状态判定条件含义redirect该 worktree 的.beads/redirect文件存在使用共享数据库重定向到主仓库或其他.beadslist会额外解析并显示重定向目标redirect → 目标目录名shared.beads目录存在且与主仓库.beads为同一目录该 worktree 就是主仓库is main共享数据库所在地local.beads目录存在但不是主仓库目录worktree 拥有自己的本地.beads通常属于意外情况见下文排查none无.beads目录尚未初始化 beads人类可读输出为对齐的表格NAME PATH BRANCH BEADS (main) /path/to/repo main shared feature-auth /path/to/repo/feature-auth feature-auth redirect → .beads特殊容错即使仓库尚未初始化 beads无.beads目录list也会回退到纯 git 枚举listWorktreesWithoutBeads此时所有 worktree 的 beads 状态显示为none方便在bd init之前预览仓库结构。bd worktree remove带失败关闭式安全检查的删除remove子命令是bd worktree中最讲究安全的部分它不是简单调用git worktree remove而是经过一套观察—审批—复验—执行的多阶段策略runWorktreeRemovalOrchestration 编排策略定义见 internal/worktreeremove/policy.gobd worktree remove name [flags]FlagsFlag说明--force跳过洁净性与包含性检查fail-closed 的注册身份与并发变更检查不会被跳过--merged-into ref要求目标 HEAD 包含在指定 ref 中与--force互斥各自最多指定一次默认无--force执行的安全检查未提交变更目标 worktree 必须干净git status --porcelain为空未推送提交目标 HEAD 必须包含在配置的上游分支或--merged-into指定的比较基准中stash 检查策略会核对目标的注册身份、HEAD、目录与 git 管理目录的一致性并发防护删除前执行复验阶段用 SHA-256 指纹目录树、git marker、脏文件路径与内容确认目标在准备与执行之间没有被并发修改任何不变量漂移都会中止删除并明确提示nothing was removedobserveRevalidation 实现目标识别支持按绝对路径、当前目录相对路径、主仓库相对路径或 basename 解析若名字歧义如两个同名 worktree会报错要求使用绝对路径resolveRegisteredWorktree.gitignore 清理若目标路径曾由bd worktree create写入.gitignore删除成功后会同步清理该条目.gitignore在复验阶段也纳入一致性检查。错误语义删除与.gitignore清理不是原子的。若删除成功但清理失败命令返回worktreeRemovalPartialError明确报告worktree 已删除、但某阶段失败、未回滚绝不假装一切正常错误类型定义。bd worktree remove feature-auth # 默认安全检查 bd worktree remove feature-auth --merged-into main # 要求 HEAD 已合并进 main bd worktree remove feature-auth --force # 跳过洁净/包含检查不推荐--merged-into的取值必须是完整 ref、无歧义的短 ref 名或完整 commit OIDHEAD、ORIG_HEAD等 worktree 本地伪引用以及refs/worktree等本地 ref 命名空间会被显式拒绝isWorktreeLocalPseudoref / isWorktreeLocalRef。底层机制.beads/redirect文件与数据库发现bd worktree之所以零配置共享数据库依赖两层机制git common directory 发现worktree 的.git是指向主仓库 git 目录的标记文件beads 通过 git 命令与目录探测自动定位主仓库.beads即上文list中的shared状态redirect 重定向internal/beads中定义了RedirectFileName redirect[internal/beads/beads.go#L32-L33]其内容为一行指向目标.beads目录的路径相对路径以.beads的父目录——即项目根——为基准解析。FollowRedirect在解析时遵循明确的契约[internal/beads/beads.go#L95-L187]忽略空行与#注释行取首个有效路径目标必须是存在的目录且包含有效数据库存在metadata.json否则忽略该 redirect 并回退原路径防呆避免落入空目录导致bd list静默无数据不支持链式重定向目标若自身含 redirect 文件则告警忽略防止死循环每次进程对同一来源只告警一次避免刷屏warnInvalidRedirectTargetOnce。bd worktree info中的beads_redirected与list中的redirect状态均由 GetRedirectInfo 与 getRedirectTarget 基于该文件计算。配套测试覆盖了相对路径解析、非法目标忽略、链式重定向阻止等场景internal/beads/beads_test.go 中TestFollowRedirect系列用例。实战一库多工作树的完整工作流依据配套指南 docs/reference/worktrees.md推荐工作流如下。1. 在主仓库初始化 beads仅一次cd project bd init2. 用 git 正常创建关联 worktree然后在其中直接使用 bdgit worktree add ../project-feature feature-branch cd ../project-feature bd ready bd create Implement feature X -t feature -p 1worktree 自动共享主仓库的.beads——无需sync.branch、无需 beads 托管的 git worktreebd会从 linked worktree 自动发现仓库的.beads目录docs/reference/worktrees.md。3. 通过 Dolt 远程同步议题数据bd dolt pull bd dolt push4. 外部议题工作区可选若希望多个代码仓库共享一个独立的议题跟踪仓库可将BEADS_DIR指向该工作区此时bd dolt push/bd dolt pull作用于外部 beads 工作区而非代码仓库export BEADS_DIR~/project-beads/.beads cd ~/project/main bd list cd ~/project/feature-1 bd list cd ~/project/feature-2 bd list5. Hooksbeads 安装的 git hooks 是 worktree 感知的若 hooks 过时或仍引用已移除的旧 sync 命令刷新即可bd hooks install疑难排查在 worktree 中找不到数据库确认主仓库存在.beads目录且该 worktree 隶属于同一仓库git worktree list cd /path/to/main/repo ls -la .beads若仓库尚无 beads 工作区先在主仓库执行bd initdocs/reference/worktrees.md。出现多个.beads目录正常情况下所有 worktree 共享仓库级工作区。若某 worktree 意外带有自己的.beadsbd worktree list中显示为local在确认其不含独有议题数据后移除或归档多余副本。多写入者并发普通单用户 worktree 用法可直接执行命令真正的跨机器 / 多 Agent 多写场景应频繁用bd dolt pull/bd dolt push同步并通过 tracker 协调避免多人同时处理同一议题docs/reference/worktrees.md。清理旧版残留早期 beads 版本存在实验性sync.branch工作流会创建.git/beads-worktrees/branch/之类的隐藏 worktree该工作流现已移除。若旧 checkout 因残留 worktree 占用分支而无法切换清理记录rm -rf .git/beads-worktrees rm -rf .git/worktrees/beads-* git worktree prune若旧配置仍含 sync 分支清空它bd config set sync.branch 总结bd worktree将 Git 原生的多工作树能力与 beads 的共享议题数据库无缝衔接create负责安全建树并自动处理.gitignore与权限info/list提供工作树与 beads 状态的透明视图remove以失败关闭的多阶段策略守护数据安全。配合bd dolt pull/push与可选的BEADS_DIR外部工作区即可构建出适合多 Agent、多特性并行的仓库拓扑。进一步可参考 docs/reference/git-integration.md、docs/reference/protected-branches.md 与 docs/multi-agent/multi-repo-migration.md 了解多仓库迁移与分支保护策略。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考