Gridiff — Visual Table Diff

在 VS Code 中以表格方式查看 CSV 差异。Gridiff 按主键对齐记录、按字段名对齐列，让你直接看到哪个字段从什么值改成了什么值。

适合审阅游戏配置、数据表和其他 CSV 文件，支持普通 CSV、Mova 四行表头及自定义表头。所有比较均只读。

开始使用

需要 VS Code 1.85 或更高版本。

1. 在扩展面板搜索 @id:sunneeyang.gridiff，安装 Gridiff — Visual Table Diff。也可从 Visual Studio Marketplace 安装。
2. 在 VS Code 的源代码管理中打开一个 .csv 文件的差异。Gridiff 默认自动打开表格对比。
3. 检查顶部的 格式 和 主键，根据需要调整，然后审阅新增、删除和修改的记录。

比较任意两份 CSV 时，打开命令面板，运行 Gridiff: 比较两个文件…，依次选择旧版本、新版本。仅打开单个 CSV 文件不会启动对比。

打开比较的其他方式

非 CSV 文件会使用 VS Code 原生文本对比。比较过程中也可以随时点击 文本对比 查看原文。

配合 Fork 使用

在 Fork 中选择内置的 Visual Studio Code 外部 diff 工具即可。通过外部工具打开 CSV 差异后，Gridiff 会自动显示表格。

自定义外部工具时，使用 VS Code 的 CLI，参数为：

--wait --diff "$LOCAL" "$REMOTE"

审阅结束后，需要关闭原始文本差异标签，Fork 才会结束等待；仅关闭 Gridiff 表格不会结束等待。

看懂表格

原表对照把新增、删除、修改记录放在同一张表中，以新文件的记录顺序为主；删除记录参照旧文件中的相邻记录放置。表头和记录标识固定，长文本完整换行，可选中复制。

变更清单按记录列出字段变化，适合逐条审阅。两种视图都支持搜索、筛选和分页。

默认开启 仅看变动记录 和 仅看变动字段。显示的列取“新增记录中有值的字段”与“已有记录中变化的字段”的并集；只有删除记录时，显示被删除记录中有值的字段。列集合按整次比较确定，搜索和翻页不会改变表头，因此同一列里仍可能出现灰色的未变化值。取消字段筛选即可查看全部列。

表头与记录对齐

默认优先使用 id 字段作为主键，没有 id 时使用第一列。主键应在每份文件中唯一且非空；点击 主键 可以选择其他字段、组合主键，或按行号对齐。修改主键值会被视为删除旧记录并新增记录。

支持 UTF-8（含 BOM）、CRLF/LF、引号内的逗号和换行、转义双引号。字段值按原字符串比较，保留前导零、大整数、空格和空值；数值增减提示仅辅助阅读。

Mova 表的处理规则

• 按首列 id 对齐时，id 为空字符串的记录会标为“无主键记录”。它们按完整内容精确匹配并保留重复次数；无法匹配的分别显示新增、删除。空白字符及组合主键缺值仍会报错。
• 数据行只比较表头声明的字段，超出表头的尾列不显示、不计入差异。需要检查这些原始内容时，使用 文本对比。
• 不符合四行表头的枚举、结构或配置表，可手动选择 无表头 或 自定义多行表头。

设置

顶部的 格式、主键 调整只作用于当前比较。需要设置工作区默认值时，可在 VS Code 设置中搜索 Gridiff，或编辑 settings.json：

{
  "gridiff.autoOpenDiff": true,
  "gridiff.format": "auto",
  "gridiff.keyColumns": ["id"]
}

记录编号从 1 开始，包含表头；引号内换行不会增加记录编号。

常见问题

提示主键重复或缺失怎么办？ 先确认表头格式，再选择唯一且非空的字段或组合主键。也可按行号对齐，但插入、删除记录可能让后续记录错位。

为什么有些记录或列没显示？ 默认只显示变动记录和相关字段。取消顶部的两个筛选可查看全部内容。全空记录会被忽略并提示数量；Mova 超出表头的尾列按上述规则排除。

修改文件后为什么没有更新？ Gridiff 显示读取时的快照，包含 VS Code 中未保存的文本。文件修改后，点击 重新读取。

切回文本后，为什么没有再次自动打开？ 同一个文本差异标签只自动打开一次，方便你返回原文。可以使用手动命令，或关闭原差异标签后重新打开。

怎样自动更新？ 在 Gridiff 扩展的齿轮菜单中启用 Auto Update，并保持 VS Code 的扩展自动更新功能开启。通过 VSIX 安装的扩展默认关闭自动更新，需要手动开启。

用过早期本地版怎么办？ 早期版本的 ID 是 gridiff.gridiff。先卸载该版本，再安装 sunneeyang.gridiff，避免两个扩展同时响应差异；后续版本沿正式 ID 更新。

当前限制

• 只支持逗号分隔、UTF-8 编码的 CSV；不支持 XLSX、TSV，也不比较电子表格的样式或批注。
• 单侧内容最多 8 MiB；两侧记录数之和乘以合并字段数，最多 100 万单元格。每页最多 100 条记录，宽表会减少每页行数。
• 提供只读审阅，不提供编辑、合并或自动刷新。自动打开适用于 CSV 文本差异，不接管 Notebook、自定义编辑器或合并编辑器。
• 重复或空字段名、错误的 CSV 引号，以及普通 CSV 中超出表头的非空列，会提示错误；可调整格式或切换文本对比。
• Windows、Linux、远程工作区以及 Fork 完整联调尚未完成验证。

数据与许可

Gridiff 不向外部服务发送 CSV 内容，不改写源文件，也不修改 Git 索引。单元格内容按纯文本显示。

采用 MIT 许可证，完整条款随扩展提供。