Beads 分支管理指南深入解析 bd branch 命令的列表与创建机制【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd branch是 Beads CLI 中用于管理 Dolt 数据库分支的核心命令不带参数时列出仓库全部分支带一个分支名参数时基于当前 HEAD 创建新分支。本文将以bd branch为主线结合 docs/cli-reference/branch.md 官方文档与仓库源码实现讲解该命令的完整用法、底层 SQL 调用链、JSON 输出格式、适用后端限制及其并发行为帮助你像管理 Git 分支一样高效管理 Beads 的记忆数据仓库。一、命令概览一行命令两种模式根据官方文档 docs/cli-reference/branch.mdbd branch的定位是 List all branches or create a new branch即列出所有分支或创建新分支。其完整语法为bd branch [name] [flags]两种使用模式如下场景命令行为列出全部分支bd branch不带参数列出仓库当前存在的所有分支并标记当前所在分支创建新分支bd branch feature-xyz带一个分支名参数基于当前 HEAD 创建名为feature-xyz的新分支文档给出的示例即为bd branch # List all branches bd branch feature-xyz # Create a new branch named feature-xyz从 cmd/bd/branch.go 的源码可以看到该命令通过cobra.MaximumNArgs(1)严格限制参数数量最多为 1 个传 0 个参数走列出路径传 1 个参数走创建路径传 2 个以上参数则直接报错。命令归属于GroupID: sync同步命令组并使用metrics.NewCommandEvent(branch)记录命令遥测事件见 cmd/bd/command_telemetry.go 相关的遥测基础设施。二、适用后端为何必须依赖 Dolt 存储文档明确指出This command requires the Dolt storage backend.该命令要求使用 Dolt 存储后端。这一点在源码中有两处印证命令入口处的前置校验在 cmd/bd/branch.go 中命令执行的第一步便是检查usesProxiedServer()若当前处于 proxied-server代理服务模式直接返回branch is not supported in proxied-server mode错误。这意味着该命令只能在直接对接存储后端的模式下运行不支持通过代理服务器转发。底层依赖 Dolt 专属 SQL 能力分支的列出、查询与创建在底层全部映射为 Dolt 数据库引擎提供的系统表与存储过程调用详见下文第三节因此只有启用了 Dolt 存储后端的仓库才能执行本命令。从仓库目录结构看Beads 存在多套存储实现internal/storage/dolt/Dolt 服务端存储与internal/storage/embeddeddolt/内嵌 Dolt 存储。其中internal/storage/embeddeddolt/version_control.go分别实现了Branch、CurrentBranch、ListBranches三个方法而 internal/storage/dolt/store.go 中Branch方法则会在创建分支时启用 OpenTelemetry 追踪跨度span并附加dolt.branch属性用于观测性分析。这说明分支能力是 Beads 版本化存储接口storage.VersionedStorage一类接口的统一约定Dolt 是承载该能力的实现后端。三、列出分支列表内容与当前分支标记3.1 人可读文本输出不带参数执行bd branch时命令调用store.ListBranches(ctx)获取全部分支再调用store.CurrentBranch(ctx)获取当前活动分支。随后在终端输出如下形式的文本见 cmd/bd/branch.go Branches: * main feature-xyz branch-a输出规则清晰标题行 Branches:使用ui.RenderAccent着色渲染当前所在分支以*星号前缀标记并用ui.StatusInProgressStyle高亮显示其余分支以 4 个空格的缩进平铺列出无任何前缀分支列表按名称排序输出排序逻辑见下文源码分析。3.2 底层 SQL读取 dolt_branches 系统表列出分支的实现位于 internal/storage/versioncontrolops/branches.go它是 Beads 与 Dolt 之间的一层版本控制操作封装全部通过标准 SQL 完成// ListBranches returns the names of all Dolt branches, sorted by name. func ListBranches(ctx context.Context, db DBConn) ([]string, error) { rows, err : db.QueryContext(ctx, SELECT name FROM dolt_branches ORDER BY name) ... } // CurrentBranch returns the name of the active branch. func CurrentBranch(ctx context.Context, db DBConn) (string, error) { var branch string if err : db.QueryRowContext(ctx, SELECT active_branch()).Scan(branch); err ! nil { ... } return branch, nil }两个关键点值得注意dolt_branches系统表Dolt 将分支元数据暴露为一张只读系统表SELECT name FROM dolt_branches ORDER BY name会返回按名称排序的全部分支列表。分支列表的排序并非在 Go 代码中完成而是交由数据库引擎的ORDER BY完成。active_branch()函数Dolt 提供 SQL 函数返回当前会话的活动分支名。bd branch的文本输出正是利用这一函数来判定哪一行需要打上*标记。3.3 JSON 输出面向脚本与 Agent 的结构化数据bd branch支持全局的--json标志该标志在 cmd/bd/main.go 中以rootCmd.PersistentFlags().BoolVar(jsonOutput, json, false, Output in JSON format)注册。当指定--json时输出不再渲染终端文本而是打印一个 JSON 对象{ current: main, branches: [branch-a, branch-c, feature-xyz, main] }字段语义字段类型含义currentstring当前活动分支名若获取失败则为空字符串branchesarray[string]全部 Dolt 分支名按名称排序这一设计对 Agent 与脚本非常友好AI 编码代理可以直接解析 JSON 判断当前所在分支、核对分支是否存在无需解析带颜色与星号的终端文本。创建分支场景下的 JSON 输出格式见下文 4.2 节。四、创建分支基于当前 HEAD 的新分支4.1 命令行为带一个分支名参数执行bd branch name时命令调用store.Branch(ctx, branchName)创建分支。成功后在文本模式下输出Created branch: feature-xyz分支名由你自行指定命令本身不做名称格式校验直接透传给存储层。4.2 底层 SQL调用 DOLT_BRANCH 存储过程创建分支的 SQL 实现在 internal/storage/versioncontrolops/branches.go 中// CreateBranch creates a new Dolt branch from the current HEAD. func CreateBranch(ctx context.Context, db DBConn, name string) error { if _, err : db.ExecContext(ctx, CALL DOLT_BRANCH(?), name); err ! nil { return fmt.Errorf(create branch %s: %w, name, err) } return nil }通过CALL DOLT_BRANCH(?)调用 Dolt 的存储过程?为参数占位符分支名经参数绑定传入避免 SQL 注入风险新分支基于当前 HEAD创建即当前分支的最新提交快照与 Git 中git branch name的语义一致该方法会以create branch name: ...前缀包装底层错误便于定位失败原因。在 internal/storage/dolt/store.go 的DoltStore.Branch方法中创建分支还会经历以下步骤开启名为dolt.branch的追踪跨度并记录dolt.branch属性 → 从连接池获取专用数据库连接s.db.Conn(ctx)→ 执行CreateBranch→ 释放连接。连接的生命周期被严格管理确保分支创建操作独立于其他事务。4.3 JSON 输出创建分支同样支持--json此时输出{ created: my-branch }created字段返回成功创建的分支名方便 Agent 程序化确认操作结果。五、错误处理与限制根据源码 cmd/bd/branch.gobd branch的失败路径统一通过HandleErrorRespectJSON处理其行为特点为proxied-server 模式下不可用直接报branch is not supported in proxied-server mode列出失败报failed to list branches: err创建失败报failed to create branch: err参数过多因cobra.MaximumNArgs(1)限制传入 2 个及以上参数会被 Cobra 拒绝JSON 感知HandleErrorRespectJSON会依据是否开启--json决定以结构化 JSON 还是纯文本形式输出错误保证脚本侧的错误处理同样可解析。需要注意命令同时设置了SilenceUsage: true与SilenceErrors: true即发生错误时不会自动打印完整帮助信息避免刷屏干扰错误定位。六、测试验证从测试用例看命令契约仓库为bd branch提供了完整的嵌入式测试见 cmd/bd/branch_embedded_test.go该文件带//go:build cgo构建标签测试前需设置环境变量BEADS_TEST_EMBEDDED_DOLT1才会实际执行。测试用例清晰地界定了命令的行为契约list_default初始化仓库后执行bd branch断言输出中包含main分支list_json执行bd branch --json解析 JSON 后断言current main且branches非空create执行bd branch feature-xyz断言输出包含分支名且再次列出时feature-xyz已出现在列表中create_json执行bd branch my-branch --json断言created my-branchcreate_multiple连续创建branch-a、branch-b、branch-c三个分支后断言分支总数不少于 4main 3 个新分支验证分支列表的累积语义并发创建TestEmbeddedBranchConcurrent10 个 goroutine 同时执行bd branch conc-branch-N断言至少 1 个创建成功、无 panic且失败场景的错误信息包含one writer at a time——这印证了 Dolt 后端存在单写者锁机制并发写操作会被串行化并优雅报错而不是崩溃。这些测试既是回归保障也是理解命令行为契约最直接的参考任何对bd branch的改造或脚本化调用都应满足上述输出与语义约定。七、典型使用场景与最佳实践结合命令特性与仓库设计bd branch的典型使用方式包括Agent 记忆分叉Beads 将编码 Agent 的记忆数据存储在 Dolt 数据库中。在尝试激进实验如大量导入历史、重构记忆 schema前先执行bd branch查看当前分支再bd branch experiment-xyz创建独立分支把风险操作隔离在分支内失败后可安全回退脚本化状态检查在 CI 或 Agent 自动化脚本中使用bd branch --json解析current与branches程序化判断仓库当前状态结合其他版本化命令使用创建分支后可进一步使用bd checkout存储层 internal/storage/dolt/store.go 的Checkout方法基于CALL DOLT_CHECKOUT(?)实现切换分支或使用bd merge合并分支、bd log查看提交历史相关命令文档见 docs/cli-reference 目录。实践建议分支名尽量语义化如feature-xxx、experiment-xxx便于列表辨识对并发写场景要有预期Dolt 后端的单写者机制决定了高并发分支创建会被串行化测试显示 10 并发下部分请求会以one writer at a time失败重试机制是必要的脚本化调用一律加--json避免解析带颜色 ANSI 码的终端输出ui.RenderAccent等渲染在生产输出中可能混入转义序列记住该命令仅在 Dolt 后端下可用且不支持 proxied-server 模式调用前先确认当前后端形态。八、小结bd branch是 Beads 命令行中体积虽小、语义清晰的版本控制入口它以无参数列出、有参数创建的极简设计将 Dolt 的分支能力暴露给终端用户与 AI Agent底层通过dolt_branches系统表、active_branch()函数与CALL DOLT_BRANCH(?)存储过程完成全部操作并以--json输出为自动化场景提供结构化结果。结合 cmd/bd/branch.go、internal/storage/versioncontrolops/branches.go 与 cmd/bd/branch_embedded_test.go 三处源码你可以完全掌握该命令的实现细节与行为边界进而在多分支工作流中安全、高效地管理 Agent 的记忆数据。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads 分支管理指南：深入解析 bd branch 命令的列表与创建机制
Beads 分支管理指南深入解析 bd branch 命令的列表与创建机制【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd branch是 Beads CLI 中用于管理 Dolt 数据库分支的核心命令不带参数时列出仓库全部分支带一个分支名参数时基于当前 HEAD 创建新分支。本文将以bd branch为主线结合 docs/cli-reference/branch.md 官方文档与仓库源码实现讲解该命令的完整用法、底层 SQL 调用链、JSON 输出格式、适用后端限制及其并发行为帮助你像管理 Git 分支一样高效管理 Beads 的记忆数据仓库。一、命令概览一行命令两种模式根据官方文档 docs/cli-reference/branch.mdbd branch的定位是 List all branches or create a new branch即列出所有分支或创建新分支。其完整语法为bd branch [name] [flags]两种使用模式如下场景命令行为列出全部分支bd branch不带参数列出仓库当前存在的所有分支并标记当前所在分支创建新分支bd branch feature-xyz带一个分支名参数基于当前 HEAD 创建名为feature-xyz的新分支文档给出的示例即为bd branch # List all branches bd branch feature-xyz # Create a new branch named feature-xyz从 cmd/bd/branch.go 的源码可以看到该命令通过cobra.MaximumNArgs(1)严格限制参数数量最多为 1 个传 0 个参数走列出路径传 1 个参数走创建路径传 2 个以上参数则直接报错。命令归属于GroupID: sync同步命令组并使用metrics.NewCommandEvent(branch)记录命令遥测事件见 cmd/bd/command_telemetry.go 相关的遥测基础设施。二、适用后端为何必须依赖 Dolt 存储文档明确指出This command requires the Dolt storage backend.该命令要求使用 Dolt 存储后端。这一点在源码中有两处印证命令入口处的前置校验在 cmd/bd/branch.go 中命令执行的第一步便是检查usesProxiedServer()若当前处于 proxied-server代理服务模式直接返回branch is not supported in proxied-server mode错误。这意味着该命令只能在直接对接存储后端的模式下运行不支持通过代理服务器转发。底层依赖 Dolt 专属 SQL 能力分支的列出、查询与创建在底层全部映射为 Dolt 数据库引擎提供的系统表与存储过程调用详见下文第三节因此只有启用了 Dolt 存储后端的仓库才能执行本命令。从仓库目录结构看Beads 存在多套存储实现internal/storage/dolt/Dolt 服务端存储与internal/storage/embeddeddolt/内嵌 Dolt 存储。其中internal/storage/embeddeddolt/version_control.go分别实现了Branch、CurrentBranch、ListBranches三个方法而 internal/storage/dolt/store.go 中Branch方法则会在创建分支时启用 OpenTelemetry 追踪跨度span并附加dolt.branch属性用于观测性分析。这说明分支能力是 Beads 版本化存储接口storage.VersionedStorage一类接口的统一约定Dolt 是承载该能力的实现后端。三、列出分支列表内容与当前分支标记3.1 人可读文本输出不带参数执行bd branch时命令调用store.ListBranches(ctx)获取全部分支再调用store.CurrentBranch(ctx)获取当前活动分支。随后在终端输出如下形式的文本见 cmd/bd/branch.go Branches: * main feature-xyz branch-a输出规则清晰标题行 Branches:使用ui.RenderAccent着色渲染当前所在分支以*星号前缀标记并用ui.StatusInProgressStyle高亮显示其余分支以 4 个空格的缩进平铺列出无任何前缀分支列表按名称排序输出排序逻辑见下文源码分析。3.2 底层 SQL读取 dolt_branches 系统表列出分支的实现位于 internal/storage/versioncontrolops/branches.go它是 Beads 与 Dolt 之间的一层版本控制操作封装全部通过标准 SQL 完成// ListBranches returns the names of all Dolt branches, sorted by name. func ListBranches(ctx context.Context, db DBConn) ([]string, error) { rows, err : db.QueryContext(ctx, SELECT name FROM dolt_branches ORDER BY name) ... } // CurrentBranch returns the name of the active branch. func CurrentBranch(ctx context.Context, db DBConn) (string, error) { var branch string if err : db.QueryRowContext(ctx, SELECT active_branch()).Scan(branch); err ! nil { ... } return branch, nil }两个关键点值得注意dolt_branches系统表Dolt 将分支元数据暴露为一张只读系统表SELECT name FROM dolt_branches ORDER BY name会返回按名称排序的全部分支列表。分支列表的排序并非在 Go 代码中完成而是交由数据库引擎的ORDER BY完成。active_branch()函数Dolt 提供 SQL 函数返回当前会话的活动分支名。bd branch的文本输出正是利用这一函数来判定哪一行需要打上*标记。3.3 JSON 输出面向脚本与 Agent 的结构化数据bd branch支持全局的--json标志该标志在 cmd/bd/main.go 中以rootCmd.PersistentFlags().BoolVar(jsonOutput, json, false, Output in JSON format)注册。当指定--json时输出不再渲染终端文本而是打印一个 JSON 对象{ current: main, branches: [branch-a, branch-c, feature-xyz, main] }字段语义字段类型含义currentstring当前活动分支名若获取失败则为空字符串branchesarray[string]全部 Dolt 分支名按名称排序这一设计对 Agent 与脚本非常友好AI 编码代理可以直接解析 JSON 判断当前所在分支、核对分支是否存在无需解析带颜色与星号的终端文本。创建分支场景下的 JSON 输出格式见下文 4.2 节。四、创建分支基于当前 HEAD 的新分支4.1 命令行为带一个分支名参数执行bd branch name时命令调用store.Branch(ctx, branchName)创建分支。成功后在文本模式下输出Created branch: feature-xyz分支名由你自行指定命令本身不做名称格式校验直接透传给存储层。4.2 底层 SQL调用 DOLT_BRANCH 存储过程创建分支的 SQL 实现在 internal/storage/versioncontrolops/branches.go 中// CreateBranch creates a new Dolt branch from the current HEAD. func CreateBranch(ctx context.Context, db DBConn, name string) error { if _, err : db.ExecContext(ctx, CALL DOLT_BRANCH(?), name); err ! nil { return fmt.Errorf(create branch %s: %w, name, err) } return nil }通过CALL DOLT_BRANCH(?)调用 Dolt 的存储过程?为参数占位符分支名经参数绑定传入避免 SQL 注入风险新分支基于当前 HEAD创建即当前分支的最新提交快照与 Git 中git branch name的语义一致该方法会以create branch name: ...前缀包装底层错误便于定位失败原因。在 internal/storage/dolt/store.go 的DoltStore.Branch方法中创建分支还会经历以下步骤开启名为dolt.branch的追踪跨度并记录dolt.branch属性 → 从连接池获取专用数据库连接s.db.Conn(ctx)→ 执行CreateBranch→ 释放连接。连接的生命周期被严格管理确保分支创建操作独立于其他事务。4.3 JSON 输出创建分支同样支持--json此时输出{ created: my-branch }created字段返回成功创建的分支名方便 Agent 程序化确认操作结果。五、错误处理与限制根据源码 cmd/bd/branch.gobd branch的失败路径统一通过HandleErrorRespectJSON处理其行为特点为proxied-server 模式下不可用直接报branch is not supported in proxied-server mode列出失败报failed to list branches: err创建失败报failed to create branch: err参数过多因cobra.MaximumNArgs(1)限制传入 2 个及以上参数会被 Cobra 拒绝JSON 感知HandleErrorRespectJSON会依据是否开启--json决定以结构化 JSON 还是纯文本形式输出错误保证脚本侧的错误处理同样可解析。需要注意命令同时设置了SilenceUsage: true与SilenceErrors: true即发生错误时不会自动打印完整帮助信息避免刷屏干扰错误定位。六、测试验证从测试用例看命令契约仓库为bd branch提供了完整的嵌入式测试见 cmd/bd/branch_embedded_test.go该文件带//go:build cgo构建标签测试前需设置环境变量BEADS_TEST_EMBEDDED_DOLT1才会实际执行。测试用例清晰地界定了命令的行为契约list_default初始化仓库后执行bd branch断言输出中包含main分支list_json执行bd branch --json解析 JSON 后断言current main且branches非空create执行bd branch feature-xyz断言输出包含分支名且再次列出时feature-xyz已出现在列表中create_json执行bd branch my-branch --json断言created my-branchcreate_multiple连续创建branch-a、branch-b、branch-c三个分支后断言分支总数不少于 4main 3 个新分支验证分支列表的累积语义并发创建TestEmbeddedBranchConcurrent10 个 goroutine 同时执行bd branch conc-branch-N断言至少 1 个创建成功、无 panic且失败场景的错误信息包含one writer at a time——这印证了 Dolt 后端存在单写者锁机制并发写操作会被串行化并优雅报错而不是崩溃。这些测试既是回归保障也是理解命令行为契约最直接的参考任何对bd branch的改造或脚本化调用都应满足上述输出与语义约定。七、典型使用场景与最佳实践结合命令特性与仓库设计bd branch的典型使用方式包括Agent 记忆分叉Beads 将编码 Agent 的记忆数据存储在 Dolt 数据库中。在尝试激进实验如大量导入历史、重构记忆 schema前先执行bd branch查看当前分支再bd branch experiment-xyz创建独立分支把风险操作隔离在分支内失败后可安全回退脚本化状态检查在 CI 或 Agent 自动化脚本中使用bd branch --json解析current与branches程序化判断仓库当前状态结合其他版本化命令使用创建分支后可进一步使用bd checkout存储层 internal/storage/dolt/store.go 的Checkout方法基于CALL DOLT_CHECKOUT(?)实现切换分支或使用bd merge合并分支、bd log查看提交历史相关命令文档见 docs/cli-reference 目录。实践建议分支名尽量语义化如feature-xxx、experiment-xxx便于列表辨识对并发写场景要有预期Dolt 后端的单写者机制决定了高并发分支创建会被串行化测试显示 10 并发下部分请求会以one writer at a time失败重试机制是必要的脚本化调用一律加--json避免解析带颜色 ANSI 码的终端输出ui.RenderAccent等渲染在生产输出中可能混入转义序列记住该命令仅在 Dolt 后端下可用且不支持 proxied-server 模式调用前先确认当前后端形态。八、小结bd branch是 Beads 命令行中体积虽小、语义清晰的版本控制入口它以无参数列出、有参数创建的极简设计将 Dolt 的分支能力暴露给终端用户与 AI Agent底层通过dolt_branches系统表、active_branch()函数与CALL DOLT_BRANCH(?)存储过程完成全部操作并以--json输出为自动化场景提供结构化结果。结合 cmd/bd/branch.go、internal/storage/versioncontrolops/branches.go 与 cmd/bd/branch_embedded_test.go 三处源码你可以完全掌握该命令的实现细节与行为边界进而在多分支工作流中安全、高效地管理 Agent 的记忆数据。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考