企业官网建设流程全解析

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

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

bd 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可以是以下三类值：

在底层，两个引用会先经过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.go）：

• Added（新增）：以+前缀展示新 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 --json

DiffEntry结构定义在 internal/storage/versioned.go：DiffType取值"added"、"modified"、"removed"；OldValue在added时为nil，NewValue在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.DiffInTx（internal/storage/issueops/diff.go）：

SELECT 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 mode（cmd/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