Branch Diff Explorer

English | 简体中文

現在のGitブランチに関連する変更のみを確認するための、完全ローカルのVS Code拡張機能です。ライセンスチェック、使用制限、テレメトリ、有料機能はありません。

機能

• コミット済み、ステージ済み、未ステージの変更全体で追加と削除を検索します。

• 複数のコミットやGit状態で変更された場合でも、ディレクトリツリーには各変更パスを1回だけ表示します。その行数は最終的な差分のみを反映します。

• 削除されたファイルはディレクトリツリーとその表示合計から除外します。削除を含む完全な比較スコープは、MCPのscopeTotalsを通じて引き続き利用できます。

• サイドバーの+ / −サマリーは、ディレクトリツリーに現在表示されているファイルを常に合計するため、検索、グロブ、ファイルタイプ、除外パスの変更が即座に反映されます。

• ブランチを任意のローカルまたはリモートのベースブランチと比較します。

• ファイル変更種別、Git状態、拡張子、グロブパターンでフィルタリングします。

• 通常の変更、作成者フィルタリング済みの変更、単一コミットをVS Codeのネイティブな並列差分エディタで開きます。

• ファイル行はベースブランチから作業ツリーへの完全な差分を開きます。単一コミットが選択されている場合は、そのコミットの親からコミットへの差分を開きます。

• ディレクトリツリーと差分エディタは同じGitマージベースを使用するため、分岐後にベースブランチに独立して追加された変更がブランチ差分の左側に漏れることはありません。

• コミット作成者でフィルタリングする場合、ファイル差分には一致する作成者のハイライトされた変更のみが含まれ、現在のファイルの残りは表示されたままになります。

• 別のコミットが周囲のコンテキストを変更したり、純粋な追加や混合置換ブロック内に挿入したり、後でファイル名を変更したりしても、作成者のハイライトは正確に保たれます。大きな編集ブロックでは、一般的な中括弧や空白を照合する前に、関数シグネチャなどの一意の行をアンカーとして使用します。作成者の編集が上書きされたり、安全な照合範囲を超えて移動された場合、差分タイトルはそれを黙って隠すのではなく明示します。

• 作成者フィルタリングされた行は、一致するすべてのコミットを加算したり他の作成者の変更を含めたりするのではなく、エディタに表示される最終的なauthor-before → working treeの行数を使用します。

• ベースブランチに存在しないファイルの場合、現在のファイル全体が表示されたままになり、選択した作成者の行のみがハイライトされます。

• 仮想Git差分ペインから定義、宣言、型定義、実装へ移動します。移動先はアクティブなワークスペースのソースで開きます。

• 一度に1つのコミットを検査します。

• コミット作成者でブランチ差分をフィルタリングします。 1人以上の作成者を選択すると、選択したベース以降のコミットによって生成されたパッチのみが表示されます。Author containsフィールドは、名前またはメールアドレスのキーワードでもフィルタリングします。

• 作成者フィルタリングは、250コミットで黙って停止するのではなく、ブランチ範囲全体をスキャンします。一致するパッチは、大規模な履歴では制限付きバッチで読み込まれます。

• ベースのGit差分を変更せずに、ファイル、ディレクトリ、またはグロブ（src/generated、src/legacy.c、**/test/**）を除外します。除外には、各エントリを個別に変更または削除できる、コンパクトでスクロール可能なエディタを使用します。

• フィルタリング後に現在表示されているすべてのファイルを、選択したディレクトリにエクスポートします。エクスポートはリポジトリのディレクトリツリーを保持し、各ソースファイル名に.diffを追加し、標準の統合差分マーカーとハンクを含みます。

• バンドルされた読み取り専用のSTDIO MCPサーバーを通じて、保存されたセッションとそのライブなフィルタリング済みGitデータをローカルAIクライアントに公開します。MCPは、ツリーおよびエクスポートアクションと同じ作成者、検索、ステータス、拡張子、グロブ、除外パス、削除ファイルのルールを使用します。

• 変更されたファイルを右クリックして、開く、差分を開く、除外する、OSのファイルマネージャで表示する、相対パス・絶対パス・ファイル名・URIをコピーすることができます。ディレクトリを右クリックして、ディレクトリ全体を除外する、エクスプローラまたはOSで表示する、その中を検索する、パス・名前・URIをコピーすることができます。

• レビューアーコックピット互換性：.diffly/findings.jsonを読み取り、ブリーフィング、所見、未完了項目を表示し、Agree/Skipのトリアージをサポートし、開いているエディタでフラグ付きの行を装飾します。

• 選択したベースブランチが現在のブランチより先行している場合に表示し、Git状態または.diffly/findings.jsonが変更されたときに更新します。

• マルチルートワークスペースをサポートし、セッション中に選択したリポジトリを記憶します。

• 無制限の名前付きセッションを作成します。各セッションは、ワークスペースフォルダ、ベースブランチ、作成者/コミットスコープ、検索オプション、ファイルフィルタ、除外パスをVS Codeワークスペースストレージに個別に保存します。

Related MCP server: GitPilot MCP

使用方法

1. VS CodeでGitリポジトリを開きます。

2. アクティビティバーからBranch Diffを開くか、Branch Diff Explorer: Open Sidebarを実行します。

3. ベースブランチを選択します。デフォルトはorigin/HEAD、次にmain、次にmasterから自動検出されます。

4. 必要に応じて作成者またはコミットを選択します。作成者モードは、まだコミット作成者がいないため、未コミットの作業を意図的に非表示にします。

5. マルチルートワークスペースでは、Workspace folderを選択します。Sessionピッカーの+、名前変更、削除コントロールを使用して、独立した差分設定を管理します。

6. Branch Diff Explorer: Open Settingsを開いて、ベースブランチ、プレビュー行数制限、Git出力バッファ、Gitコマンドのタイムアウトを設定します。エラーUIからもこれらの設定にリンクできます。

7. ヘッダーのExport filtered diffsボタン（⇩）を使用し、ターゲットディレクトリを選択して、既存のエクスポート済み.diffファイルを上書きする前に確認します。

8. ヘッダーのMCPを使用して、CodexまたはClaude Codeの設定をコピーするか、ローカルMCPセルフテストを実行します。サーバーにはNode.js 18以降が必要です。nodeがPATHにない場合は、MCP: Node Commandを設定します。

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クライアントは自然言語リクエストからツールを選択できます。信頼性が高くトークン効率の良いレビューのために、クライアントに次の順序で実行するよう依頼してください：

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は、意図的に異なる2つの合計を報告します：

• scopeTotalsは、UIファイルフィルタ前の完全な作成者またはコミットスコープを表します。

• visibleTotalsは、すべてのUIフィルタ後にlist_diff_files、エクスポート、ディレクトリツリーで利用可能な非削除ファイルを正確に表します。

Author containsを使用する場合、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行、1回の呼び出しで最大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 を押すと、Extension Development Host が起動します。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。