Beads 的 Git 集成指南hooks、worktree 与分支工作流【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 是一个为编码 Agent 提供记忆升级的轻量级议题跟踪系统。本指南以 docs/reference/git-integration.md 为核心系统讲解 Beads 如何把 Git 当作配置宿主与自动同步触发器从.beads/目录结构、五类托管 Git hooks 的安装/卸载/超时机制到外部 Hook 管理器lefthook、husky、pre-commit 等的协同方式再到 worktree、特性分支、Fork、团队协作与 Jujutsu 无分支工作流。读完本文你将能独立完成 Beads 与 Git 的深度整合配置并理解其底层实现原理。OverviewBeads 与 Git 的分工Beads 对 Git 的依赖集中在两个维度项目托管Project hosting你的代码仓库同时也是 Beads 配置的载体——.beads/config.yaml、.beads/metadata.json等配置随代码一起版本化Hooks 自动同步通过安装 Git hooks在 commit、merge、push、checkout 等 Git 操作发生时自动触发 Beads 的导出/导入逻辑。需要强调的是Beads 的议题数据本身并不存在 Git 分支里而是存放在 Dolt一个带版本控制的 SQL 数据库中。议题数据跨机器同步走的是bd dolt pull/bd dolt push与 Git 提交完全解耦——具体同步模型见 docs/core-concepts/sync-concepts.md。File Structure.beads/目录的职责划分bd init在仓库根目录创建的标准目录结构如下.beads/ ├── config.yaml # 项目配置git 跟踪 ├── metadata.json # 后端元数据git 跟踪 ├── .gitignore # 由 bd init 写入git 跟踪 ├── embeddeddolt/ # Dolt 数据库——嵌入式模式默认git 忽略 └── dolt/ # Dolt 数据库——服务器模式git 忽略关键约定bd init会自动写入.beads/.gitignore把数据库目录和运行时文件排除在 Git 之外无需手动编写任何 gitignore 规则严禁把数据库目录.beads/embeddeddolt/或.beads/dolt/纳入 Git 或 Git LFS 跟踪——数据库是本地/共享状态不是应该进提交的对象。Git Hooks五类托管 Hook 与安装机制安装与刷新bd init默认会安装 hooks可用bd init --skip-hooks跳过。手动安装或刷新bd hooks install从源码看bd hooks install管理的 hook 名集合定义在 cmd/bd/hooks.go#L24 的managedHookNames中共五个pre-commit、post-merge、pre-push、post-checkout、prepare-commit-msg。安装后的 hook 是薄垫片thin shim只负责调用bd hooks run hook-nameHook作用pre-commit运行链式 hooks当export.auto开启时导出.beads/issues.jsonl使其进入同一次提交post-merge运行链式 hooks仅在未配置 Dolt remote 时作为传统回退导入 JSONL——设置了sync.remote后bd dolt pull才是正规同步途径pre-push在 push 前运行链式 hookspost-checkout分支切换后运行链式 hooksprepare-commit-msg当 AgentBD_ACTOR环境变量执行提交时追加Executed-By:身份 trailer分节标记Section Markers与已有 hooks 共存的关键shims 使用分节标记与仓库已有的 hooks 共存——标记之外的内容在反复安装与升级中会被完整保留。标记格式为# --- BEGIN BEADS INTEGRATION vX.Y.Z ---与# --- END BEADS INTEGRATION vX.Y.Z ---其注入逻辑实现在 cmd/bd/hooks.go#L139 的injectHookSection找到成对的 BEGIN/END 就只替换中间内容遇到孤立或顺序颠倒的坏标记先清理再注入无标记时追加到文件末尾若文件以exec结尾则注入到 exec 块之前避免新节不可达对应 cmd/bd/hooks.go#L195 的findExecBlockInjectionPoint。升级bd后被委托的 hook 行为bd hooks run内部逻辑随新版本自动更新shim 本身生成的 shell 策略属于已安装内容只有重新执行安装/刷新才会变化。若从旧版本升级后需要刷新已安装的 hook 分节执行一次bd hooks install即可。三种安装变体bd hooks install --beads # 安装到 .beads/hooks/Dolt 后端推荐 bd hooks install --shared # 安装到 .beads-hooks/可版本化、随团队共享 bd hooks install --chain # 先运行已有 hooks再运行 bd hooks从实现看cmd/bd/hooks.go#L869 的installHooksWithOptions默认安装到git rev-parse --git-common-dir解析出的共享 hooks 目录天然 worktree 感知——从链接 worktree 安装也能正确定位共享 Git 目录--beads与--shared会写入core.hooksPath指向绝对路径cmd/bd/hooks.go#L1279 的configureSharedHooksPath、cmd/bd/hooks.go#L1299 的configureBeadsHooksPath因为在 worktree 中相对路径会相对 worktree 根解析而找不到主仓库的 hooks--shared模式安装到可提交的.beads-hooks/目录方便团队共享记得提交该目录--beads/--shared模式切换 hooks 目录时会先把此前生效目录如全局core.hooksPath或默认.git/hooks中的既有 hooks 迁移保留避免静默丢失preservePreexistingHookscmd/bd/hooks.go#L997其中针对 husky v8/v9 还有专门的路径修复逻辑fixHuskyHookLayoutcmd/bd/hooks.go#L1106。另外安装前有写入安全护栏guardHookWritePathcmd/bd/hooks.go#L812拒绝覆盖指向别处的符号链接、拒绝改写非 bd 拥有且被 Git 跟踪的 hook 文件改写他人 hook 前会先创建.backup副本。状态查看与卸载bd hooks list # 查看安装状态installed / outdated / missing bd hooks uninstall # 卸载 bd hooksbd hooks uninstall只移除 BEGIN/END 标记内的 bd 分节仅剩 shebang 时才删除整个文件并恢复此前备份的非 bd hook若检测到core.hooksPath指向 bd 管理的目录会一并重置cmd/bd/hooks.go#L1321。外部 Hook 管理器External Hook Managersbd 能检测以下外部 Git hook 管理器并检查其配置是否调用了bd hooks runlefthook— YAML/TOML/JSON 配置husky—.husky/目录脚本pre-commit—.pre-commit-config.yamlprek— 基于 Rust 的 pre-commit 替代品配置格式相同hk— 使用 Pkl 配置的快速 hook 管理器overcommit— 基于 Ruby仅检测yorkie— 仅检测simple-git-hooks— 轻量 JS 方案仅检测各管理器的配置文件路径清单定义在 cmd/bd/doctor/fix/hooks.go#L32 的hookManagerConfigs中对于 lefthook、husky、pre-commit/prek、hk 这几类可解析配置的管理器CheckExternalHookManagerIntegrationcmd/bd/doctor/fix/hooks.go#L555会解析其配置并判断bd hooks run是否被调用overcommit、yorkie、simple-git-hooks 因无法验证配置内容仅做检测提示。bd doctor会报告检测到的管理器是否已与 bd 集成bd doctor --fix则会以--chain方式重装 hooks保证管理器既有 hooks 继续运行cmd/bd/doctor/fix/hooks.go#L595 的GitHooks修复函数。对于基于配置的管理器直接把 bd 步骤写进配置即可。以hk.pkl为例hooks { [pre-commit] { steps { [bd-pre-commit] { check bd hooks run pre-commit } } } [post-merge] { steps { [bd-post-merge] { check bd hooks run post-merge } } } [pre-push] { steps { [bd-pre-push] { check bd hooks run pre-push \$\ } } } }Hook 超时机制hook shim 对bd hooks run施加软超时前提是系统中有兼容的辅助工具只会在 GNU coreutils 身份探测成功后才使用timeout或gtimeout从而避开原生 Windows 放在PATH上、命令行不兼容的timeout.exeGNU timeout 在到达截止时间时发送TERMPOSIX 主机上若无 GNU timeoutPerl 回退方案在截止时间对直接bd进程使用SIGALRM但 Git for Windows 自带的 Perl 不保证 alarm 能跨exec生效因此那里优先推荐 GNU coreutils。默认截止时间是 300 秒5 分钟足以容纳链式 pre-commit 流水线eslint、prettier、TypeScript 编译等。默认值定义在 cmd/bd/hooks.go#L56 的hookTimeoutSeconds常量可用环境变量BEADS_HOOK_TIMEOUT覆盖# 设置更长的超时单位秒 export BEADS_HOOK_TIMEOUT600 # 10 分钟 # 或仅在单次调用时设置 BEADS_HOOK_TIMEOUT600 git commit -m ...取值必须是正整数秒。非法值和 0 会产生警告并回落到 300 秒默认值shim 中的校验逻辑见 cmd/bd/hooks.go#L78 生成的 hook 脚本片段。需要明确两点边界这是软进程截止不是进程树级隔离对 TERM 免疫的工作或后代进程可能存活超时若既没有 GNU timeout 也没有 Perlhook 会警告并以无截止方式直接运行——该兜底路径可能一直挂起直到 hook 自身返回。超时到达时beads 打印警告并放行Git 操作——commit 或 push 不会被阻断shim 对 coreutils 退出码 124 / Perl 退出码 142 统一转为 0 退出见 cmd/bd/hooks.go#L121。Conflict Resolution冲突交给 DoltDolt 在数据库层利用内建 merge 能力处理合并冲突。同步时若发生冲突Dolt 会识别冲突行并允许通过 SQL 进行解决。# 检查并修复冲突 bd doctor --fixProtected Branches受保护分支不受影响Dolt 把数据存在refs/dolt/data下与 Git refs 完全分离。这意味着beads 数据不会与受保护的 Git 分支冲突不需要额外的beads-sync分支也无需为受保护分支开特例在带有 Gitorigin的新项目上bd init会自动把该 origin 配置为 Dolt remote。完整的受保护分支工作流含旧版beads-sync清理见 docs/reference/protected-branches.md。Git Worktrees多工作树共享同一工作区Beads 在 Git worktree 中无需额外配置即可工作。链接 worktree 会自动发现仓库的.beads工作区并通过 Dolt 同步议题数据# 在链接 worktree 中 bd create Task bd list bd dolt pull bd dolt push要点详见 docs/reference/worktrees.md所有 worktree共享仓库的同一个.beads工作区发现顺序是BEADS_DIR若设置→ 主仓库的.beads从而避免跨 worktree 重复建库用bd where作为判断当前激活工作区的权威手段——worktree 中本地./.beads缺失是完全正常的嵌入式模式默认同一时刻只服务一个写者若需跨 worktree 并发写入请使用服务器模式旧版 beads 文档中通过创建隐藏 Git worktree 实现的sync.branch工作流已被移除当前同步一律使用 Dolt remotes。若需要让多个代码 worktree 共享一个独立的议题跟踪仓库可把BEADS_DIR指向外部工作区此时bd dolt push/pull以外部 beads 工作区为目标而非代码仓库。Branch Workflows三种分支协作模式特性分支Feature Branchgit checkout -b feature-x bd create Feature X -t feature # 工作... bd dolt push git pushFork 工作流开源贡献者场景# 在 fork 中 bd init --contributor # 交互式向导 # 在独立的规划仓库中工作... bd dolt pushcontributor 向导把议题数据保留在独立的规划仓库中上游仓库不残留任何.beads/。它最适合开源贡献者、独立开发者以及希望在公开仓库上做私有任务跟踪的场景。bd init会自动检测 fork并提议配置.git/info/exclude--setup-exclude让 beads 文件只留在本地也可以用--role contributor或--role maintainer非交互模式下的默认值免提示直接设定角色。团队工作流Team Workflowbd init --team # 所有团队成员共享同一个 Dolt 数据库 bd dolt pull # 从 Dolt remote 拉取最新变更 bd dolt push # 推送你的变更到 Dolt remote最适合实行受保护分支与评审后合并review-before-merge策略的团队。多仓库模式见 docs/multi-agent/multi-repo-migration.md。合并后的重复检测bd duplicates --auto-mergeBranchless WorkflowsJujutsu (jj) 无分支工作流由于 beads 数据存放在 Dolt而非 Git 分支中不存在对当前分支概念的依赖因此 Beads 可以配合 Jujutsu (jj) 这类无分支 VCS 工具使用。无需 hooks 也能工作的功能功能需要 Hooks说明bd create、bd update、bd close否核心 CRUD 直接使用 Doltbd ready、bd list、bd show否只读查询bd dolt push/bd dolt pull否Dolt 原生同步与 Git 无关bd onboard、bd doctor否诊断与引导Agent 身份 trailer是prepare-commit-msghook 为提交追加Executed-By:Hook 链式执行是保留既有的 pre-commit、post-merge hooks初始化时完全跳过 hooksbd init --skip-hooks不生成 AGENTS.md 的选项bd init生成的 AGENTS.md 文件为 AI Agent 提供指令。若你想自行管理 Agent 指令或不想让 beads 改动被跟踪的文件bd init --skip-agents # 跳过 AGENTS.md 以及 Claude/Codex 配置生成 bd init --stealth # 完整隐形模式同时跳过 hooks agents这些 flag 的定义在 cmd/bd/init.go#L2281 附近其中--stealth还会持久化no-git-ops: true并配置仓库级 Git 设置让 beads 在隐形模式下运行。Jujutsu 的具体配置Colocated 仓库jj git init --colocateGit hooks 正常工作。Beads 安装简化版 hooks仅pre-commit与post-merge无暂存逻辑。纯 jj 仓库无 Gitjj 目前没有原生 hooks需要配置 push 别名# ~/.config/jj/config.toml [aliases] push [util, exec, --, sh, -c, bd dolt commit bd dolt push jj git push \$\, ]之后用jj push代替jj git push。Best Practices日常最佳实践安装 hooks—bd hooks install定期推送— 会话结束时执行bd dolt push工作前先拉取—bd dolt pull获取最新议题使用常规 Git worktrees— 不需要 sync 分支进一步阅读Git Worktrees 完整指南 — 多工作树共享与BEADS_DIR外部工作区受保护分支工作流 — 含旧版beads-sync清理同步概念 — 议题数据如何跨机器流动多仓库迁移 — 多工作区模式Hook 实现源码 与 外部管理器检测源码 — 深入了解本文涉及的底层机制【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads 的 Git 集成指南：hooks、worktree 与分支工作流
Beads 的 Git 集成指南hooks、worktree 与分支工作流【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 是一个为编码 Agent 提供记忆升级的轻量级议题跟踪系统。本指南以 docs/reference/git-integration.md 为核心系统讲解 Beads 如何把 Git 当作配置宿主与自动同步触发器从.beads/目录结构、五类托管 Git hooks 的安装/卸载/超时机制到外部 Hook 管理器lefthook、husky、pre-commit 等的协同方式再到 worktree、特性分支、Fork、团队协作与 Jujutsu 无分支工作流。读完本文你将能独立完成 Beads 与 Git 的深度整合配置并理解其底层实现原理。OverviewBeads 与 Git 的分工Beads 对 Git 的依赖集中在两个维度项目托管Project hosting你的代码仓库同时也是 Beads 配置的载体——.beads/config.yaml、.beads/metadata.json等配置随代码一起版本化Hooks 自动同步通过安装 Git hooks在 commit、merge、push、checkout 等 Git 操作发生时自动触发 Beads 的导出/导入逻辑。需要强调的是Beads 的议题数据本身并不存在 Git 分支里而是存放在 Dolt一个带版本控制的 SQL 数据库中。议题数据跨机器同步走的是bd dolt pull/bd dolt push与 Git 提交完全解耦——具体同步模型见 docs/core-concepts/sync-concepts.md。File Structure.beads/目录的职责划分bd init在仓库根目录创建的标准目录结构如下.beads/ ├── config.yaml # 项目配置git 跟踪 ├── metadata.json # 后端元数据git 跟踪 ├── .gitignore # 由 bd init 写入git 跟踪 ├── embeddeddolt/ # Dolt 数据库——嵌入式模式默认git 忽略 └── dolt/ # Dolt 数据库——服务器模式git 忽略关键约定bd init会自动写入.beads/.gitignore把数据库目录和运行时文件排除在 Git 之外无需手动编写任何 gitignore 规则严禁把数据库目录.beads/embeddeddolt/或.beads/dolt/纳入 Git 或 Git LFS 跟踪——数据库是本地/共享状态不是应该进提交的对象。Git Hooks五类托管 Hook 与安装机制安装与刷新bd init默认会安装 hooks可用bd init --skip-hooks跳过。手动安装或刷新bd hooks install从源码看bd hooks install管理的 hook 名集合定义在 cmd/bd/hooks.go#L24 的managedHookNames中共五个pre-commit、post-merge、pre-push、post-checkout、prepare-commit-msg。安装后的 hook 是薄垫片thin shim只负责调用bd hooks run hook-nameHook作用pre-commit运行链式 hooks当export.auto开启时导出.beads/issues.jsonl使其进入同一次提交post-merge运行链式 hooks仅在未配置 Dolt remote 时作为传统回退导入 JSONL——设置了sync.remote后bd dolt pull才是正规同步途径pre-push在 push 前运行链式 hookspost-checkout分支切换后运行链式 hooksprepare-commit-msg当 AgentBD_ACTOR环境变量执行提交时追加Executed-By:身份 trailer分节标记Section Markers与已有 hooks 共存的关键shims 使用分节标记与仓库已有的 hooks 共存——标记之外的内容在反复安装与升级中会被完整保留。标记格式为# --- BEGIN BEADS INTEGRATION vX.Y.Z ---与# --- END BEADS INTEGRATION vX.Y.Z ---其注入逻辑实现在 cmd/bd/hooks.go#L139 的injectHookSection找到成对的 BEGIN/END 就只替换中间内容遇到孤立或顺序颠倒的坏标记先清理再注入无标记时追加到文件末尾若文件以exec结尾则注入到 exec 块之前避免新节不可达对应 cmd/bd/hooks.go#L195 的findExecBlockInjectionPoint。升级bd后被委托的 hook 行为bd hooks run内部逻辑随新版本自动更新shim 本身生成的 shell 策略属于已安装内容只有重新执行安装/刷新才会变化。若从旧版本升级后需要刷新已安装的 hook 分节执行一次bd hooks install即可。三种安装变体bd hooks install --beads # 安装到 .beads/hooks/Dolt 后端推荐 bd hooks install --shared # 安装到 .beads-hooks/可版本化、随团队共享 bd hooks install --chain # 先运行已有 hooks再运行 bd hooks从实现看cmd/bd/hooks.go#L869 的installHooksWithOptions默认安装到git rev-parse --git-common-dir解析出的共享 hooks 目录天然 worktree 感知——从链接 worktree 安装也能正确定位共享 Git 目录--beads与--shared会写入core.hooksPath指向绝对路径cmd/bd/hooks.go#L1279 的configureSharedHooksPath、cmd/bd/hooks.go#L1299 的configureBeadsHooksPath因为在 worktree 中相对路径会相对 worktree 根解析而找不到主仓库的 hooks--shared模式安装到可提交的.beads-hooks/目录方便团队共享记得提交该目录--beads/--shared模式切换 hooks 目录时会先把此前生效目录如全局core.hooksPath或默认.git/hooks中的既有 hooks 迁移保留避免静默丢失preservePreexistingHookscmd/bd/hooks.go#L997其中针对 husky v8/v9 还有专门的路径修复逻辑fixHuskyHookLayoutcmd/bd/hooks.go#L1106。另外安装前有写入安全护栏guardHookWritePathcmd/bd/hooks.go#L812拒绝覆盖指向别处的符号链接、拒绝改写非 bd 拥有且被 Git 跟踪的 hook 文件改写他人 hook 前会先创建.backup副本。状态查看与卸载bd hooks list # 查看安装状态installed / outdated / missing bd hooks uninstall # 卸载 bd hooksbd hooks uninstall只移除 BEGIN/END 标记内的 bd 分节仅剩 shebang 时才删除整个文件并恢复此前备份的非 bd hook若检测到core.hooksPath指向 bd 管理的目录会一并重置cmd/bd/hooks.go#L1321。外部 Hook 管理器External Hook Managersbd 能检测以下外部 Git hook 管理器并检查其配置是否调用了bd hooks runlefthook— YAML/TOML/JSON 配置husky—.husky/目录脚本pre-commit—.pre-commit-config.yamlprek— 基于 Rust 的 pre-commit 替代品配置格式相同hk— 使用 Pkl 配置的快速 hook 管理器overcommit— 基于 Ruby仅检测yorkie— 仅检测simple-git-hooks— 轻量 JS 方案仅检测各管理器的配置文件路径清单定义在 cmd/bd/doctor/fix/hooks.go#L32 的hookManagerConfigs中对于 lefthook、husky、pre-commit/prek、hk 这几类可解析配置的管理器CheckExternalHookManagerIntegrationcmd/bd/doctor/fix/hooks.go#L555会解析其配置并判断bd hooks run是否被调用overcommit、yorkie、simple-git-hooks 因无法验证配置内容仅做检测提示。bd doctor会报告检测到的管理器是否已与 bd 集成bd doctor --fix则会以--chain方式重装 hooks保证管理器既有 hooks 继续运行cmd/bd/doctor/fix/hooks.go#L595 的GitHooks修复函数。对于基于配置的管理器直接把 bd 步骤写进配置即可。以hk.pkl为例hooks { [pre-commit] { steps { [bd-pre-commit] { check bd hooks run pre-commit } } } [post-merge] { steps { [bd-post-merge] { check bd hooks run post-merge } } } [pre-push] { steps { [bd-pre-push] { check bd hooks run pre-push \$\ } } } }Hook 超时机制hook shim 对bd hooks run施加软超时前提是系统中有兼容的辅助工具只会在 GNU coreutils 身份探测成功后才使用timeout或gtimeout从而避开原生 Windows 放在PATH上、命令行不兼容的timeout.exeGNU timeout 在到达截止时间时发送TERMPOSIX 主机上若无 GNU timeoutPerl 回退方案在截止时间对直接bd进程使用SIGALRM但 Git for Windows 自带的 Perl 不保证 alarm 能跨exec生效因此那里优先推荐 GNU coreutils。默认截止时间是 300 秒5 分钟足以容纳链式 pre-commit 流水线eslint、prettier、TypeScript 编译等。默认值定义在 cmd/bd/hooks.go#L56 的hookTimeoutSeconds常量可用环境变量BEADS_HOOK_TIMEOUT覆盖# 设置更长的超时单位秒 export BEADS_HOOK_TIMEOUT600 # 10 分钟 # 或仅在单次调用时设置 BEADS_HOOK_TIMEOUT600 git commit -m ...取值必须是正整数秒。非法值和 0 会产生警告并回落到 300 秒默认值shim 中的校验逻辑见 cmd/bd/hooks.go#L78 生成的 hook 脚本片段。需要明确两点边界这是软进程截止不是进程树级隔离对 TERM 免疫的工作或后代进程可能存活超时若既没有 GNU timeout 也没有 Perlhook 会警告并以无截止方式直接运行——该兜底路径可能一直挂起直到 hook 自身返回。超时到达时beads 打印警告并放行Git 操作——commit 或 push 不会被阻断shim 对 coreutils 退出码 124 / Perl 退出码 142 统一转为 0 退出见 cmd/bd/hooks.go#L121。Conflict Resolution冲突交给 DoltDolt 在数据库层利用内建 merge 能力处理合并冲突。同步时若发生冲突Dolt 会识别冲突行并允许通过 SQL 进行解决。# 检查并修复冲突 bd doctor --fixProtected Branches受保护分支不受影响Dolt 把数据存在refs/dolt/data下与 Git refs 完全分离。这意味着beads 数据不会与受保护的 Git 分支冲突不需要额外的beads-sync分支也无需为受保护分支开特例在带有 Gitorigin的新项目上bd init会自动把该 origin 配置为 Dolt remote。完整的受保护分支工作流含旧版beads-sync清理见 docs/reference/protected-branches.md。Git Worktrees多工作树共享同一工作区Beads 在 Git worktree 中无需额外配置即可工作。链接 worktree 会自动发现仓库的.beads工作区并通过 Dolt 同步议题数据# 在链接 worktree 中 bd create Task bd list bd dolt pull bd dolt push要点详见 docs/reference/worktrees.md所有 worktree共享仓库的同一个.beads工作区发现顺序是BEADS_DIR若设置→ 主仓库的.beads从而避免跨 worktree 重复建库用bd where作为判断当前激活工作区的权威手段——worktree 中本地./.beads缺失是完全正常的嵌入式模式默认同一时刻只服务一个写者若需跨 worktree 并发写入请使用服务器模式旧版 beads 文档中通过创建隐藏 Git worktree 实现的sync.branch工作流已被移除当前同步一律使用 Dolt remotes。若需要让多个代码 worktree 共享一个独立的议题跟踪仓库可把BEADS_DIR指向外部工作区此时bd dolt push/pull以外部 beads 工作区为目标而非代码仓库。Branch Workflows三种分支协作模式特性分支Feature Branchgit checkout -b feature-x bd create Feature X -t feature # 工作... bd dolt push git pushFork 工作流开源贡献者场景# 在 fork 中 bd init --contributor # 交互式向导 # 在独立的规划仓库中工作... bd dolt pushcontributor 向导把议题数据保留在独立的规划仓库中上游仓库不残留任何.beads/。它最适合开源贡献者、独立开发者以及希望在公开仓库上做私有任务跟踪的场景。bd init会自动检测 fork并提议配置.git/info/exclude--setup-exclude让 beads 文件只留在本地也可以用--role contributor或--role maintainer非交互模式下的默认值免提示直接设定角色。团队工作流Team Workflowbd init --team # 所有团队成员共享同一个 Dolt 数据库 bd dolt pull # 从 Dolt remote 拉取最新变更 bd dolt push # 推送你的变更到 Dolt remote最适合实行受保护分支与评审后合并review-before-merge策略的团队。多仓库模式见 docs/multi-agent/multi-repo-migration.md。合并后的重复检测bd duplicates --auto-mergeBranchless WorkflowsJujutsu (jj) 无分支工作流由于 beads 数据存放在 Dolt而非 Git 分支中不存在对当前分支概念的依赖因此 Beads 可以配合 Jujutsu (jj) 这类无分支 VCS 工具使用。无需 hooks 也能工作的功能功能需要 Hooks说明bd create、bd update、bd close否核心 CRUD 直接使用 Doltbd ready、bd list、bd show否只读查询bd dolt push/bd dolt pull否Dolt 原生同步与 Git 无关bd onboard、bd doctor否诊断与引导Agent 身份 trailer是prepare-commit-msghook 为提交追加Executed-By:Hook 链式执行是保留既有的 pre-commit、post-merge hooks初始化时完全跳过 hooksbd init --skip-hooks不生成 AGENTS.md 的选项bd init生成的 AGENTS.md 文件为 AI Agent 提供指令。若你想自行管理 Agent 指令或不想让 beads 改动被跟踪的文件bd init --skip-agents # 跳过 AGENTS.md 以及 Claude/Codex 配置生成 bd init --stealth # 完整隐形模式同时跳过 hooks agents这些 flag 的定义在 cmd/bd/init.go#L2281 附近其中--stealth还会持久化no-git-ops: true并配置仓库级 Git 设置让 beads 在隐形模式下运行。Jujutsu 的具体配置Colocated 仓库jj git init --colocateGit hooks 正常工作。Beads 安装简化版 hooks仅pre-commit与post-merge无暂存逻辑。纯 jj 仓库无 Gitjj 目前没有原生 hooks需要配置 push 别名# ~/.config/jj/config.toml [aliases] push [util, exec, --, sh, -c, bd dolt commit bd dolt push jj git push \$\, ]之后用jj push代替jj git push。Best Practices日常最佳实践安装 hooks—bd hooks install定期推送— 会话结束时执行bd dolt push工作前先拉取—bd dolt pull获取最新议题使用常规 Git worktrees— 不需要 sync 分支进一步阅读Git Worktrees 完整指南 — 多工作树共享与BEADS_DIR外部工作区受保护分支工作流 — 含旧版beads-sync清理同步概念 — 议题数据如何跨机器流动多仓库迁移 — 多工作区模式Hook 实现源码 与 外部管理器检测源码 — 深入了解本文涉及的底层机制【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考