企业官网建设流程全解析

Beads 受保护分支（Protected Branches）完全指南：基于 Dolt 命名空间隔离，无需任何保护分支变通方案

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

Beads（bd）是一款为编码 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.go），sync.branch只作为历史别名保留兼容处理，不再参与当前同步路径。这意味着同步通道已经从「Git 分支」彻底迁移到了「Dolt 远程」。

为什么受保护分支是安全的：Dolt 与 Git 的命名空间隔离

受保护分支守护的是refs/heads/main这类Git refs，而 Dolt 把 Beads 数据存放在自己的 ref 命名空间中。这种隔离带来三个直接保证：

1. bd create、bd update、bd close不会在main上产生任何提交；
2. bd dolt push推送的是 Dolt 数据，而不是代码分支；
3. 正常的代码变更依然走你现有的 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 init

bd 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 数据库目录保持 gitignored，issue 数据通过 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 push

bd 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 prune

3. 远程残留的beads-sync分支：如果远程还存在仅为旧工作流服务的beads-sync分支，在确认当前所有 issue 数据都已通过 Dolt 同步后，按仓库策略归档或删除即可。

4. 刷新过期的 hooks：若旧 hooks 仍引用已移除的同步命令，运行：

bd hooks install

hooks 安装是 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 形式，可使用git+ssh://git@github.com/org/repo.git或git+https://github.com/org/repo.git（docs/core-concepts/sync-concepts.md 修复章节）。

场景二：bd dolt pull期间发生冲突

Dolt 在数据库层面报告冲突，与 Git 分支冲突相互独立。使用失败命令输出的合并策略提示或 doctor 指引解决：

bd vc merge <branch> --strategy [ours|theirs] bd doctor --fix

bd vc merge的语义是：--strategy ours冲突时优先保留我们的变更，--strategy theirs优先保留对方的变更（见 docs/cli-reference/vc.md）。bd doctor --fix则用于检查并修复配置漂移、过期 hooks 等问题。

场景三：过期 hooks 提到旧的同步命令

刷新生成的 hooks：

bd hooks install

bd hooks install生成的 shim 使用分节标记与现有 hooks 共存，标记之外的内容在安装与升级过程中会被保留；升级bd后 shim 调用的bd hooks run <hook-name>行为会自动更新（详见 docs/reference/git-integration.md 的 hooks 章节）。bd hooks list可查看状态，bd hooks uninstall可卸载。

设计要点回顾：为什么这条路径能成立

一个常见的误区是：用常规的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