Beads `bd diff` 使用指南：对比任意两个提交或分支间的 issue 变更

Beadsbd diff使用指南对比任意两个提交或分支间的 issue 变更【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsbd diff是 Beads 提供的版本对比命令用于展示两个提交或分支之间 issue事务项的差异支持 commit 哈希、分支名与HEAD等特殊引用。本文以 docs/cli-reference/diff.md 为骨架结合仓库源码深入讲解命令的参数规则、输出格式、底层 Doltdolt_diff()实现与测试验证方式帮助你完成分支评审、版本回溯与变更审计。命令定位与基本用法bd diff隶属于views命令组是一条只读的视图类命令位于 cmd/bd/diff.go。其完整用法为bd diff from-ref to-ref [flags]命令要求恰好两个位置参数源码中通过cobra.ExactArgs(2)强制校验cmd/bd/diff.go分别表示对比的起点引用与终点引用。官方文档给出的三个典型示例bd diff main feature-branch # 对比 main 与 feature 分支 bd diff HEAD~5 HEAD # 查看最近 5 次提交引入的变更 bd diff abc123 def456 # 对比两个具体提交docs/cli-reference/diff.md是命令行文档体系的一部分由bd help --doc diff自动生成文件头部标注了AUTO-GENERATED说明因此它与 cmd/bd/diff.go 中diffCmd的Long描述保持一致可作为命令行为的权威依据。支持的三类引用ref文档明确规定from-ref与to-ref可以是以下三类值引用类型示例说明提交哈希commit hashabc123def、abc123定位到某个具体提交的快照分支名branch namemain、feature-branch定位到分支当前所指向的提交特殊引用HEAD、HEAD~1Git/Dolt 风格的相对与指针引用在底层两个引用会先经过ValidateRef校验internal/storage/issueops/as_of.go引用不能为空、长度不得超过 128 字符且只能匹配正则^[a-zA-Z0-9_./-]$。这意味着分支名可以包含点号和斜杠例如release/v2.0、feature/auth.flow这类命名都能通过校验而包含空格或特殊符号的非法输入会被拒绝。该校验同时服务于dolt_diff()表函数因为 Dolt 要求把 ref 作为 SQL 字符串字面量内联进查询不接受预处理绑定参数严格的字符白名单是防止 SQL 注入的关键防线这一点在 internal/storage/dolt/versioned.go 的注释中有明确说明。输出格式详解命令执行成功后输出会根据是否有变更而呈现两种形态同时支持--json标志切换为结构化输出。无变更提示当两个引用之间没有任何 issue 发生变化时直接输出一行提示No changes between from-ref and to-ref对应源码分支见 cmd/bd/diff.go。人类可读输出存在变更时命令先打印变更统计行再按added、modified、removed三种类型分组展示cmd/bd/diff.goAdded新增以前缀展示新 issue 的 ID 与标题Modified修改以~前缀展示 issue ID并额外标注发生了变化的字段可能组合出现title标题、status: open - done状态流转、priority: P1 - P2优先级变更、description描述等Removed删除以-前缀展示被删除 issue 的 ID 与原标题。字段差异的判定逻辑位于 cmd/bd/diff.go分别比较OldValue与NewValue的Title、Status、Priority、Description四个字段凡是不同的字段都会被列入变化清单。JSON 输出配合全局--json标志bd diff会直接输出一个DiffEntry数组cmd/bd/diff.go每条记录包含IssueID、DiffType以及可选的OldValue/NewValue非常适合脚本化处理与 CI 集成bd diff main feature-branch --jsonDiffEntry结构定义在 internal/storage/versioned.goDiffType取值added、modified、removedOldValue在added时为nilNewValue在removed时为nil。底层实现Dolt 的dolt_diff()表函数bd diff的核心计算并不在 CLI 层而是委托给存储层完成。命令入口调用store.Diff(ctx, fromRef, toRef)cmd/bd/diff.go在 Dolt 后端由DoltStore.Diff在一个只读事务中执行internal/storage/dolt/versioned.go最终落到issueops.DiffInTxinternal/storage/issueops/diff.goSELECT COALESCE(from_id, ) as from_id, COALESCE(to_id, ) as to_id, diff_type, from_title, to_title, from_description, to_description, from_status, to_status, from_priority, to_priority FROM dolt_diff(from-ref, to-ref, issues)其要点如下使用 Dolt 内建的dolt_diff(from, to, table)表函数直接对issues 表的两个快照做差异比对diff_type由 Dolt 给出取值即added/modified/removed通过COALESCE(from_id, to_id)提取行的标识 ID新增行没有from_id删除行没有to_id这一手法在 internal/storage/issueops/diff.go 中用于组装DiffEntry.IssueID注意从源码注释可以推断dolt_diff(from, to, table)对比的是两个快照之间的差异并不会逐条遍历中间提交见 internal/storage/dolt/versioned.go 对同类查询的说明。也就是说即使某个 issue 在区间内被删除后又重建只要它在终点快照存在就会归入added/modified而非removed。值得说明的是仓库中还实现了另一个更高层的ChangedIssueIDs方法internal/storage/dolt/versioned.go它通过UNION ALL把issues、labels、dependencies、comments四张表的dolt_diff结果合并服务于自动导出场景。这印证了 Beads 对变更检测的需求不止于 issues 主表本身——标签、依赖、评论的改动同样会被纳入视野。模式限制与注意事项Proxied-server 模式不支持bd diff在检测到代理服务器模式usesProxiedServer()时会直接报错diff is not supported in proxied-server modecmd/bd/diff.go因此该命令仅在嵌入式存储等直接模式下可用引用合法性前置校验两个 ref 参数在进入 SQL 前都会经过ValidateRef非法字符或过长的输入会得到明确报错错误信息输出命令自身设置SilenceUsage与SilenceErrors并统一经由HandleErrorRespectJSON处理错误这意味着在--json模式下错误也会以 JSON 形式返回便于自动化消费遥测每次执行会记录一个metrics.NewCommandEvent(diff)事件cmd/bd/diff.go用于统计命令使用情况。测试验证与典型工作流bd diff的 CLI 行为在 cmd/bd/diff_embedded_test.go 中有完整的嵌入式集成测试覆盖测试辅助函数包括bdDiff执行bd diff args并断言成功bdDiffFail执行后断言失败用于验证非法 ref、错误模式等场景bdDiffJSON追加--json标志执行并把输出解析为 JSON 数组验证结构化输出的正确性。实际工作中bd diff可以与其他视图类命令配合形成完整的工作流提交前用bd diff HEAD~1 HEAD快速自检最近一次改动的范围合入分支前用bd diff main feature-branch评审待合入的变更集合需要查看单个 issue 的完整演进历史时配合 bd history按 issue 维度回溯每次提交的快照需要定位到某一次具体变更的内容时用 bd show 查看某条 issue 的当前状态再结合bd diff判断从何时开始变化完整命令清单与分组views组可参考 CLI 参考索引而 Beads 面向 agent 的总体能力说明见 README.md。小结bd diff把 Dolt 底层的版本快照对比能力封装成了一条极简的双参数命令文档层面的三类 ref 规则、三种变更类型分组、字段级差异标注与 JSON 输出配合源码中ValidateRef的安全校验、dolt_diff()的 SQL 实现以及嵌入式集成测试构成了一个既可人工评审、又可脚本化消费的完整 diff 能力。需要对比两个分支或提交间的 issue 变更时bd diff from-ref to-ref就是最直接的入口。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考