Branch Diff Explorer

English | 简体中文

一款完全本地化的 VS Code 扩展，用于仅审查与当前 Git 分支相关的更改。它没有许可证检查、使用限制、遥测或付费功能。

功能

• 搜索已提交、已暂存和未暂存更改中的新增与删除内容。

• 在目录树中每个路径仅显示一次，即使它在多个提交或 Git 状态中都有更改；其行数统计仅反映最终的差异。

• 将已删除文件排除在目录树及其可见统计之外。完整的比较范围（包括删除内容）仍可通过 MCP scopeTotals 获取。

• 侧边栏的 + / − 摘要始终统计目录树中当前显示的文件，因此搜索、glob、文件类型和排除路径的更改会立即更新摘要。

• 将你的分支与任何本地或远程基础分支进行比较。

• 按文件更改类型、Git 状态、扩展名和 glob 模式进行筛选。

• 在 VS Code 原生的并排差异编辑器中打开普通更改、按作者筛选的更改以及单个提交。

• 文件行会打开从基础分支到工作树的完整差异；当选中单个提交时，它们会打开该提交的父提交到该提交的差异。

• 目录树和差异编辑器使用相同的 Git 合并基础，因此分支分叉后独立添加到基础分支的更改不会泄漏到分支差异的左侧。

• 按提交作者筛选时，文件差异仅包含匹配作者的突出显示更改，同时保留当前文件的其余部分。

• 当另一个提交更改了周围上下文、在纯新增或混合替换块中插入内容、或稍后重命名文件时，作者突出显示仍然准确。大型编辑块使用唯一行（如函数签名）作为锚点，然后再匹配常见的花括号和空白。如果作者编辑已被覆盖或移动超出安全匹配范围，差异标题会明确提示，而不是静默隐藏。

• 按作者筛选的行使用最终的 作者之前 → 工作树 行数统计，由编辑器显示，而不是累加每个匹配的提交或包含其他作者的更改。

• 对于基础分支中不存在的文件，当前文件的完整内容仍然可见，而仅突出显示所选作者的更改行。

• 从虚拟 Git 差异窗格中跳转到定义、声明、类型定义和实现；目标会在活动工作区源文件中打开。

• 一次仅检查一个提交。

• 按提交作者筛选分支差异。 选择一个或多个作者后，视图仅显示这些作者在所选基础之后提交所生成的补丁。作者包含 字段还可按姓名或电子邮件关键字进行筛选。

• 作者筛选会扫描完整的分支范围，而不是在 250 个提交处静默停止。匹配的补丁会以有界批次加载，以应对大型提交历史。

• 排除文件、目录或 glob（src/generated、src/legacy.c、**/test/**），而无需更改基础 Git 差异。排除项使用一个紧凑、可滚动的编辑器，每个条目都可以独立更改或移除。

• 将筛选后当前可见的每个文件导出到所选目录。导出会保留仓库目录树，为每个源文件名附加 .diff，并包含标准的统一差异标记和块。

• 通过内置的只读 STDIO MCP 服务器，将会话及其实时筛选的 Git 数据暴露给本地 AI 客户端。MCP 使用与树和导出操作相同的作者、搜索、状态、扩展名、glob、排除路径和已删除文件规则。

• 右键单击任何已更改文件即可打开它、打开其差异、排除它、在操作系统文件管理器中显示它，或复制其相对路径、绝对路径、文件名或 URI。右键单击目录可排除整个目录、在资源管理器或操作系统中显示它、在其中搜索，或复制其路径、名称或 URI。

• 与审查者工作流兼容：读取 .diffly/findings.json，显示简报、发现和缺失工作项，支持同意/跳过分类，并在打开的编辑器中标记被标记的行。

• 当所选基础分支领先于当前分支时显示提示，并在 Git 状态或 .diffly/findings.json 更改时刷新。

• 支持多根工作区，并在会话期间记住所选仓库。

• 创建无限数量的命名会话。每个会话将其工作区文件夹、基础分支、作者/提交范围、搜索选项、文件筛选器和排除路径独立保存在 VS Code 工作区存储中。

Related MCP server: GitPilot MCP

使用方法

1. 在 VS Code 中打开一个 Git 仓库。

2. 从活动栏打开 Branch Diff，或运行 Branch Diff Explorer: Open Sidebar（Branch Diff Explorer：打开侧边栏）。

3. 选择基础分支。默认值会自动检测，依次为 origin/HEAD、main、master。

4. 可选地选择作者或提交；作者模式会故意隐藏未提交的工作，因为它尚不具有提交作者。

5. 在多根工作区中，选择 工作区文件夹。使用 会话 选择器的 +、重命名和删除控件来管理独立的差异设置。

6. 打开 Branch Diff Explorer: Open Settings（Branch Diff Explorer：打开设置）以配置基础分支、预览行数限制、Git 输出缓冲区或 Git 命令超时。错误界面也会链接到这些设置。

7. 使用标头中的 导出筛选差异 按钮（⇩），选择目标目录，并在覆盖任何现有导出的 .diff 文件前进行确认。

8. 在标头中使用 MCP 复制 Codex 或 Claude Code 配置，或运行本地 MCP 自检。服务器要求 Node.js 18 或更高版本；如果 node 不在 PATH 中，请设置 MCP: Node Command（MCP：Node 命令）。

通过 MCP 进行 AI 访问

该扩展将其捆绑的 MCP 运行时复制到稳定的 VS Code 存储中，并保持一个工作区特定的状态文件与所有已保存的会话同步。当 AI 客户端调用时，服务器会重新计算 Git 更改；导出后的差异文件和打开的 VS Code 窗口在配置后均非必需。

对于 Codex，将生成的 TOML 复制到 ~/.codex/config.toml 或受信任项目的 .codex/config.toml 中，然后重启本地 Codex 客户端。Codex 桌面版、CLI 和 IDE 客户端均支持本地 STDIO MCP 服务器并共享此配置。参见 Codex MCP 官方文档。

对于 Claude Code，将生成的 JSON 对象合并到项目的 .mcp.json 中，然后重新连接客户端。生成的配置仅包含本地 Node 命令、捆绑的服务器路径和工作区状态文件路径。

推荐的 MCP 工作流

MCP 客户端可以从自然语言请求中选择工具。为了获得可靠且节省 token 的审查，请让客户端遵循以下顺序：

1. 调用 list_diff_sessions 查找活动或请求的会话。

2. 调用 get_diff_summary 确认仓库、分支、比较基础、作者或提交范围、筛选器以及可见统计。

3. 翻页浏览 list_diff_files 以获取目录树中显示的确切文件集。

4. 为每个正在审查的文件读取 get_filtered_diff。

5. 当补丁不包含足够的周围源代码时，使用 read_file_context。

6. 仅当需要完整的全作者分支更改进行比较时，才使用 get_branch_diff。

MCP 工具参考

所有工具均为只读，并接受可选的 sessionId。省略时，将使用活动的 Branch Diff Explorer 会话。

get_diff_summary 报告两个有意不同的统计：

• scopeTotals 描述应用界面文件筛选器之前的完整作者或提交范围。

• visibleTotals 精确描述应用所有界面筛选器后，可通过 list_diff_files、导出和目录树获取的未删除文件。

使用 作者包含 时，get_filtered_diff.text 仅包含匹配作者的补丁。其每个文件的 additions 和 deletions 与最终可见的“作者之前到工作树”差异一致；它们既不累加重复提交，也不包含其他作者。get_branch_diff 有意包含其他作者的更改，因此在按作者范围的审查中不得用它替代 get_filtered_diff。

read_file_context.side 接受：

• current（默认）：当前工作树内容。

• head：HEAD 处的文件。

• base：比较所使用的 Git 合并基础处的文件。

• author_before：将所选作者的补丁还原后的当前内容，与 VS Code 按作者筛选差异的左侧一致。此侧仅在按作者筛选的会话中可用。

分页示例

文件和提交列表返回 nextCursor。将其传回，直到它不再出现：

{
  "sessionId": "session-id",
  "pathPrefix": "src/services",
  "cursor": 0,
  "limit": 100
}

差异和源代码工具返回 nextStartLine。文本页默认 800 行，每次调用最多支持 5,000 行：

{
  "sessionId": "session-id",
  "path": "src/services/example.ts",
  "startLine": 1,
  "maxLines": 1000
}

始终使用 list_diff_files 返回的精确仓库相对路径。

建议的审查提示

Use the branch-diff-explorer MCP. First list the saved diff sessions and
summarize the active session. Page through every file returned by
list_diff_files. Review get_filtered_diff so the review remains limited to the
selected author or commit, and use read_file_context when full source context is
needed. Use get_branch_diff only to compare the selected-author patch with the
complete branch change. Report findings with severity, file path, relevant
lines, reasoning, and a suggested fix.

有用的聚焦请求包括：

Search the active filtered changes for glfs_bdev_get_route_stats, then read the
matching file's filtered diff and its current and author_before source context.

Review only files under source/services/spdk. Use pathPrefix when listing files,
follow every pagination cursor, and do not review changes from other authors.

MCP 故障排除

• 如果服务器缺失，请重启 Codex 或 Claude 客户端并检查其 MCP 服务器列表。在 Codex 中，使用 /mcp。

• 如果结果看起来过期，请使用 refresh: true 调用 get_diff_summary。

• 如果路径被拒绝，请从 list_diff_files 重新获取并传递返回的精确路径。

• 如果响应被截断，请遵循 nextCursor 或 nextStartLine，而不是假设结果完整。

• author_before 需要按作者筛选的会话。

• 二进制文件、符号链接目标和大于 32 MB 的源文件不会作为源代码上下文返回。

该扩展仅调用本地 git 可执行文件，不会通过网络发送源代码、提交元数据、审查结果或搜索查询。MCP 服务器是本地 STDIO，不暴露任何监听网络端口。

开发

npm install
npm run check
npm test
npm run build

在 VS Code 中按 F5 启动扩展开发主机。使用 npm run package 构建 VSIX。

简体中文

Branch Diff Explorer 是一个完全在本地运行的 VS Code 插件，用于只查看和 审查当前 Git 分支相关的改动。插件没有许可证校验、使用次数限制、遥测或付费 功能。

功能

• 搜索已提交、已暂存和未暂存改动中的新增行与删除行。

• 目录树中每个路径只显示一次，即使文件经过多次提交或同时存在于多个 Git 状态；文件的增删行数只反映最终 Diff，不累加中间提交。

• 已删除文件不会显示在目录树及其可见汇总中；包含删除文件的完整比较范围仍可 通过 MCP scopeTotals 获取。

• 侧栏顶部的 + / − 始终汇总目录树当前显示的文件，因此搜索、Glob、文件类型 或排除路径发生变化后会立即重新统计。

• 可以与任意本地或远程基线分支比较。

• 支持按变更类型、Git 状态、扩展名和 Glob 表达式过滤。

• 普通分支改动、作者过滤改动和单次提交都使用 VS Code 原生左右对比窗口打开。

• 点击文件时打开基线分支到当前工作区的完整 Diff；选择 Single commit 时，则 打开该提交的父提交到该提交的 Diff。

• 目录树和 Diff 编辑器使用相同的 Git merge base，因此分支分叉后基线分支 新增的无关改动不会混入 Diff 左侧。

• 按 Commit Author 过滤时，Diff 仍显示完整当前文件，但只高亮匹配作者的改动。

• 即使其他提交修改了周围上下文、在纯新增或混合替换块中继续插入内容，或者 后续重命名文件，作者高亮仍会尽量保持准确。较大的编辑块会优先使用函数签名 等唯一代码行作为锚点，再匹配常见的大括号和空白行。如果某项作者改动已经被 覆盖或移动到无法安全定位的位置，Diff 标题会明确提示，而不会静默遗漏。

• Author 模式下文件行数使用编辑器实际显示的最终 author-before → working tree Diff 统计，既不会重复累加作者的多次提交，也 不会混入其他作者的改动。

• 如果文件在基线分支中不存在，Diff 会显示完整当前文件，但只高亮选定作者添加 的代码行。

• 可以从虚拟 Git Diff 窗口执行 Go to Definition、Declaration、Type Definition 和 Implementation，目标会在当前 Workspace 的真实源码中打开。

• 支持一次只查看和审查一个提交。

• 按提交作者过滤分支 Diff。 可以通过 Author contains 使用姓名或邮箱 关键字筛选提交。

• 作者过滤会扫描完整分支提交范围，不会在 250 个提交处静默停止；大型提交历史 会按有界批次读取匹配补丁。

• 支持排除文件、目录或 Glob，例如 src/generated、src/legacy.c、 **/test/**，不会改变底层基线 Diff。排除项使用紧凑的可滚动编辑器，每一项 都能单独修改或删除。

• 可以把当前过滤后可见的全部文件导出到指定目录。导出会保留仓库目录结构， 在源码文件名后添加 .diff，内容包含标准 Unified Diff 标记和 Hunk。

• 通过内置的只读 STDIO MCP Server，把已保存会话及其实时过滤后的 Git 数据 提供给本地 AI 客户端。MCP 与目录树和导出功能使用相同的作者、搜索、状态、 扩展名、Glob、排除路径和删除文件规则。

• 文件右键菜单支持打开文件、打开 Diff、加入排除、在系统文件管理器中显示， 以及复制相对路径、绝对路径、文件名或 URI。目录右键菜单支持排除整个目录、 在 Explorer 或系统文件管理器中显示、在目录内搜索，以及复制路径、目录名或 URI。

• 兼容 Reviewer Cockpit：读取 .diffly/findings.json，显示审查摘要、问题和 缺失项，支持 Agree/Skip 分类，并在已打开编辑器中装饰问题行。

• 当基线分支领先当前分支时给出提示，并在 Git 状态或 .diffly/findings.json 发生变化时刷新。

• 支持 Multi-root Workspace，并在会话中记住所选仓库。

• 可以创建任意数量的命名会话。每个会话分别保存 Workspace folder、基线分支、 Author/Commit 范围、搜索选项、文件过滤器和排除路径。

使用方法

1. 在 VS Code 中打开一个 Git 仓库。

2. 从 Activity Bar 打开 Branch Diff，或者执行命令 Branch Diff Explorer: Open Sidebar。

3. 选择基线分支。默认依次从 origin/HEAD、main、master 自动检测。

4. 可选：设置 Author contains 或选择 Single commit。Author 模式会主动隐藏 未提交改动，因为这些改动没有 Commit Author。

5. 在 Multi-root Workspace 中选择 Workspace folder。使用 Session 下拉框旁的新增、重命名和删除按钮管理相互独立的 Diff 配置。

6. 执行 Branch Diff Explorer: Open Settings 配置默认基线分支、预览行数、 Git 输出缓冲区或 Git 命令超时。异常界面也提供设置入口。

7. 点击顶部的 Export filtered diffs（⇩），选择目标目录，并在覆盖已有 .diff 文件前确认。

8. 点击顶部 MCP，复制 Codex 或 Claude Code 配置，或者运行本地 MCP 自检。MCP Server 要求 Node.js 18 或更高版本；如果 node 不在 PATH 中， 请设置 MCP: Node Command。

通过 MCP 向 AI 提供改动

插件会把内置 MCP 运行文件复制到稳定的 VS Code 存储目录，并把所有已保存会话 同步到当前 Workspace 专属的状态文件。AI 调用工具时，MCP Server 会重新计算 Git 改动；完成配置后不要求预先导出 Diff，也不要求 VS Code 窗口一直打开。

Codex：点击 MCP → Copy Codex MCP configuration，把生成的 TOML 添加到 ~/.codex/config.toml，或者受信任项目的 .codex/config.toml，然后重启 Codex 客户端。Codex Desktop、CLI 和 IDE 插件支持本地 STDIO MCP，并共享同一 份配置。参见 Codex MCP 官方文档。

Claude Code：点击 MCP → Copy Claude Code MCP configuration，把生成的 JSON 合并到项目 .mcp.json 中，然后重新连接客户端。生成的配置只包含本地 Node 命令、内置 Server 路径和 Workspace 状态文件路径。

推荐的 MCP 调用流程

MCP 客户端可以根据自然语言请求自动选择工具。为了让审查稳定并减少 Token 消耗，建议让 AI 按以下顺序调用：

1. 调用 list_diff_sessions 找到活动会话或指定会话。

2. 调用 get_diff_summary 确认仓库、当前分支、基线分支、Author/Commit 范围、过滤条件和可见文件汇总。

3. 分页调用 list_diff_files，获取目录树中实际显示的完整文件集合。

4. 对需要审查的文件调用 get_filtered_diff。

5. 当补丁上下文不足时，使用 read_file_context 读取完整源码。

6. 只有在需要对比所有作者的完整分支改动时，才调用 get_branch_diff。

MCP 工具说明

所有工具都是只读的，并接受可选的 sessionId。不传时使用 Branch Diff Explorer 当前活动会话。

get_diff_summary 会返回两组含义不同的汇总：

• scopeTotals：应用 UI 文件过滤前，完整 Author 或 Commit 范围的汇总。

• visibleTotals：应用全部 UI 过滤并移除 deleted 文件后，实际可通过 list_diff_files、导出和目录树访问的汇总。

启用 Author contains 时，get_filtered_diff.text 只包含匹配作者的补丁； 其中每个文件的 additions 和 deletions 与最终可见的 author-before → working tree Diff 一致，既不会累加作者的多次提交，也不会 混入其他作者。 get_branch_diff 会有意包含其他作者的改动，因此 Author 审查时不能用它替代 get_filtered_diff。

read_file_context.side 支持：

• current（默认）：当前工作区内容。

• head：HEAD 中的文件内容。

• base：本次比较所使用的 Git merge base 内容。

• author_before：在当前文件中撤销所选作者补丁后的内容，对应 VS Code Author Diff 左侧。仅 Author 过滤会话支持此模式。

分页示例

文件和提交列表会返回 nextCursor。持续把它传回下一次调用，直到返回值中不再 包含该字段：

{
  "sessionId": "session-id",
  "pathPrefix": "src/services",
  "cursor": 0,
  "limit": 100
}

Diff 和源码工具会返回 nextStartLine。文本页默认返回 800 行，每次最多支持 5,000 行：

{
  "sessionId": "session-id",
  "path": "src/services/example.ts",
  "startLine": 1,
  "maxLines": 1000
}

文件参数必须使用 list_diff_files 返回的精确仓库相对路径。

推荐审查提示词

使用 branch-diff-explorer MCP。先列出已保存的 Diff 会话并汇总当前活动会话，
然后分页读取 list_diff_files 返回的全部文件。使用 get_filtered_diff 审查文件，
确保范围只包含当前选择的 Author 或 Commit；需要完整源码上下文时调用
read_file_context。只有需要把作者补丁与完整分支改动比较时才调用
get_branch_diff。输出问题严重程度、文件路径、相关行、原因和修复建议。

针对特定内容搜索：

在当前过滤后的改动中搜索 glfs_bdev_get_route_stats，然后读取匹配文件的
filtered diff、current 源码和 author_before 源码上下文。

只审查特定目录：

只审查 source/services/spdk 下的文件。调用 list_diff_files 时使用
pathPrefix，跟随所有分页 cursor，并且不要审查其他作者的改动。

MCP 排障

• 如果客户端中没有 Server，重启 Codex 或 Claude 客户端并检查 MCP Server 列表；Codex 中可以使用 /mcp。

• 如果结果看起来没有更新，调用 get_diff_summary 时传入 refresh: true。

• 如果路径被拒绝，重新从 list_diff_files 获取并传入完全一致的路径。

• 如果响应被截断，继续跟随 nextCursor 或 nextStartLine，不要把当前页当作 完整结果。

• author_before 要求当前会话已经启用 Author 过滤。

• MCP 不会把二进制文件、符号链接目标或超过 32 MB 的文件作为源码上下文返回。

插件只调用本地 git 命令，不会通过网络发送源码、Commit Metadata、Reviewer 问题或搜索内容。MCP Server 使用本地 STDIO，不会监听网络端口。

开发

npm install
npm run check
npm test
npm run build

在 VS Code 中按 F5 启动 Extension Development Host。使用 npm run package 构建 VSIX。