Beads 受保护分支Protected Branches完全指南基于 Dolt 命名空间隔离无需任何保护分支变通方案【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeadsbd是一款为编码 Agent 设计的记忆与问题追踪工具它将 issue 数据存放在 Dolt 数据库中而不是写入你的代码提交历史。本文基于 docs/reference/protected-branches.md 展开讲解为什么在 GitHub、GitLab、Bitbucket 等平台启用分支保护Protected Branch后Beads 依然可以正常工作且不需要任何beads-sync分支、保护分支例外或 beads 管理的 Git worktree同时给出团队协作的标准流程、旧版sync.branch遗留配置的清理步骤以及bd dolt push/pull的常见故障排查方法。读完本文你将掌握在严格分支保护策略下安全使用 Beads 的完整实战方案。核心结论当前版本不需要保护分支变通方案Beads 在当前版本中不需要受保护分支的 workaround。原因在于数据存储架构Issue 数据存储在 Dolt 中位于refs/dolt/data命名空间下与main等普通 Git 分支完全分离Beads 的所有命令不会把 issue 更新提交到你的当前代码分支上因此 GitHub、GitLab、Bitbucket 的分支保护规则只作用于你的代码历史对 Beads 的数据读写毫无影响。从源码结构看sync.remote任意 Dolt 兼容的远程 URL是当前同步配置的主键而旧的sync.git-remote已被标记为 Deprecated见 internal/config/yaml_config.gosync.branch只作为历史别名保留兼容处理不再参与当前同步路径。这意味着同步通道已经从「Git 分支」彻底迁移到了「Dolt 远程」。为什么受保护分支是安全的Dolt 与 Git 的命名空间隔离受保护分支守护的是refs/heads/main这类Git refs而 Dolt 把 Beads 数据存放在自己的 ref 命名空间中。这种隔离带来三个直接保证bd create、bd update、bd close不会在main上产生任何提交bd dolt push推送的是 Dolt 数据而不是代码分支正常的代码变更依然走你现有的 Pull Request 流程分支保护规则照常生效。底层原理可参见 docs/core-concepts/sync-concepts.md本地 Dolt 数据库是bd list、bd show、bd ready以及所有写命令的source of truth跨机器同步走 Dolt remotes。在正常的 Git 托管项目中Dolt 远程可以直接复用代码仓库的originURL——Dolt 把 issue 历史存放在refs/dolt/data下与refs/heads/main互不干扰。bd init会自动检测git remote get-url origin并配置名为origin的 Dolt 远程首次bd dolt push即发布refs/dolt/data。当前推荐工作流初始化与同步1. 初始化 Beads在项目中初始化bd initbd init会写入.beads/.gitignore自动将数据库目录与运行时文件排除在 Git 之外无需手动编写 gitignore 规则详见 docs/reference/git-integration.md 的文件结构说明。2. 按需提交追踪配置文件如果项目策略要求提交这些小型配置文件git add .beads/.gitignore .beads/metadata.json .beads/config.yaml .gitignore git commit -m Initialize beads issue tracker.beads/目录结构如下来自 docs/reference/git-integration.md.beads/ ├── config.yaml # 项目配置git 追踪 ├── metadata.json # 后端元数据git 追踪 ├── .gitignore # bd init 写入git 追踪 ├── embeddeddolt/ # Dolt 数据库 — 嵌入式模式默认gitignore └── dolt/ # Dolt 数据库 — 服务器模式gitignore关键红线sync.remote持久化在.beads/config.yaml中务必提交该配置变更这样新克隆的运行bd bootstrap才能接上同一个 Dolt 远程见 docs/core-concepts/sync-concepts.md 的修复章节。而.beads/embeddeddolt/与.beads/dolt/数据库目录绝不能通过 Git 或 Git LFS 追踪。3. 通过 Dolt 远程同步 issue 数据本地 Dolt 数据库目录保持 gitignoredissue 数据通过 Dolt 远程同步bd dolt pull bd dolt push整个过程不需要beads-syncGit 分支、保护分支例外也不需要 beads 管理的 Git worktree。团队协作共享追踪器标准流程对于共享的 issue 追踪器推荐流程是bd init --team bd dolt pull bd ready bd update id --claim bd dolt push核心纪律开始工作前先 pull交接工作前先 push这样其他克隆才能看到最新的 issue 状态。该流程与 docs/reference/git-integration.md 的团队工作流章节一致——「Best for teams on protected branches and review-before-merge policies」即它本身就是为启用分支保护、实行合前评审review-before-merge的团队设计的。分支工作流的自然融合在受保护分支的仓库中普通代码流程完全不受影响git checkout -b feature-x bd create Feature X -t feature # 工作... bd dolt push git pushbd dolt push推送 Dolt 数据git push推送代码分支两者各走各的通道。合并分支后可运行bd duplicates --auto-merge进行重复 issue 检测。遗留 sync-branch 清理从旧工作流迁移旧工作流的历史背景早期 Beads 版本曾记录过一个实验性的sync.branch工作流把.beads变更提交到beads-sync之类的分支并在.git/beads-worktrees/下使用隐藏的 Git worktree。该工作流已被移除。CHANGELOG 中可见其演进轨迹早期曾「auto-sets sync.branch to current git branch」后来「Rejects main/master as sync branch」并增加「Stale sync branch detection - Warns about abandoned beads-sync branches」最终被 Dolt 远程同步取代CHANGELOG.md。注意仓库中的 examples/protected-branch/README.md 与 examples/team-workflow/README.md 仍记录着旧版sync.branch演示如bd init --branch beads-metadata属于历史遗留示例当前版本不推荐再按此配置。清理步骤1. 清除旧的 sync 分支配置bd config set sync.branch 2. 若过期的隐藏 worktree 阻止分支切换删除它们并修剪 Git 的 worktree 注册表rm -rf .git/beads-worktrees rm -rf .git/worktrees/beads-* git worktree prune3. 远程残留的beads-sync分支如果远程还存在仅为旧工作流服务的beads-sync分支在确认当前所有 issue 数据都已通过 Dolt 同步后按仓库策略归档或删除即可。4. 刷新过期的 hooks若旧 hooks 仍引用已移除的同步命令运行bd hooks installhooks 安装是 worktree-aware 的从链接 worktree 中安装也能正确解析共享 Git 目录见 docs/reference/worktrees.md。故障排查场景一bd dolt push提示没有远程添加或检查 Dolt 远程bd dolt remote list bd dolt remote add origin remote-url bd dolt push对于 Dolt 兼容的 Git URL 形式可使用gitssh://gitgithub.com/org/repo.git或githttps://github.com/org/repo.gitdocs/core-concepts/sync-concepts.md 修复章节。场景二bd dolt pull期间发生冲突Dolt 在数据库层面报告冲突与 Git 分支冲突相互独立。使用失败命令输出的合并策略提示或 doctor 指引解决bd vc merge branch --strategy [ours|theirs] bd doctor --fixbd vc merge的语义是--strategy ours冲突时优先保留我们的变更--strategy theirs优先保留对方的变更见 docs/cli-reference/vc.md。bd doctor --fix则用于检查并修复配置漂移、过期 hooks 等问题。场景三过期 hooks 提到旧的同步命令刷新生成的 hooksbd hooks installbd hooks install生成的 shim 使用分节标记与现有 hooks 共存标记之外的内容在安装与升级过程中会被保留升级bd后 shim 调用的bd hooks run hook-name行为会自动更新详见 docs/reference/git-integration.md 的 hooks 章节。bd hooks list可查看状态bd hooks uninstall可卸载。设计要点回顾为什么这条路径能成立关注点说明证据数据存放位置Dolt 的refs/dolt/data独立于refs/heads/*docs/reference/git-integration.md写操作行为bd create/update/close不触碰当前代码分支docs/reference/protected-branches.md同步通道bd dolt push/pull与 git push 无关docs/core-concepts/sync-concepts.md同步配置sync.remote为主键sync.git-remote已废弃internal/config/yaml_config.goJSONL 的角色.beads/issues.jsonl仅作导出/互操作/备份不是跨机同步通道docs/core-concepts/sync-concepts.md一个常见的误区是用常规的bd import .beads/issues.jsonl替代bd dolt pull。JSONL 导入是仅 upsert 的无法推断「导出中缺失的记录是被删除、修剪还是从未导出过」因此不能作为跨机同步的替代方案——Dolt 远程才是唯一可靠的同步通道。延伸阅读Git 集成指南Git hooks 安装、外部 hook 管理器lefthook、husky、pre-commit 等、冲突解决与分支工作流Git Worktrees 指南从 Git worktree 使用 Beads共享单一.beads工作区BEADS_DIR外部工作区以及遗留 sync-branch 清理同步概念Dolt 作为同步 source of truth 的完整原理JSONL 导出与bd dolt push/pull的区别初始化安全恢复手册初始化相关恢复方案团队工作流示例 与 受保护分支示例注意其中记录的sync.branch演示属于已被移除的旧工作流仅作历史参考【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考