如何让Git为.v5python格式文件生成有效差异对比？

问题概述 #

VEX机器人竞赛的.v5python文件是单行JSON结构，核心Python代码嵌入在textContent字段中。Git默认将其识别为单行文件，导致diff、blame等版本控制功能完全无法正常显示代码差异。常规的*.v5python text diff=python配置因JSON嵌套结构失效，且无法改用纯.py文件或双向同步方案，需纯Git配置解决。

解决方案：自定义Git文本转换过滤器 #

通过给Git配置自定义驱动，让Git仅解析textContent字段内的Python代码，忽略其他极少变动的JSON元数据，实现正常的diff、blame和分支对比。

1. 编写解析脚本 #

在仓库根目录创建vex-git-filter.py脚本，用于提取JSON中的Python代码：

#!/usr/bin/env python3
import json
import sys

def extract_python_content():
    input_content = sys.stdin.read().strip()
    try:
        json_data = json.loads(input_content)
        print(json_data.get("textContent", ""))
    except json.JSONDecodeError:
        # 解析失败时输出原内容，避免Git抛出错误
        print(input_content)

if __name__ == "__main__":
    extract_python_content()

添加执行权限：

chmod +x vex-git-filter.py

2. 配置Git自定义驱动 #

编辑仓库的.git/config文件，添加以下配置：

[diff "vex-v5python"]
    textconv = ./vex-git-filter.py
    cachetextconv = true  # 缓存转换结果，提升大仓库性能
[blame "vex-v5python"]
    textconv = ./vex-git-filter.py

如果脚本不在仓库根目录，需替换为绝对路径。

3. 关联文件类型到驱动 #

在.gitattributes中添加规则，让Git对.v5python文件使用自定义驱动：

*.v5python    text diff=vex-v5python blame=vex-v5python

4. 验证功能 #

• 测试diff：执行git diff <目标分支> -- example.v5python，将显示textContent内Python代码的行级差异
• 测试blame：执行git blame example.v5python，将显示Python代码每一行的提交信息，而非整个单行JSON的提交记录

注意事项 #

• 若VEX IDE修改了JSON元数据字段，Git会检测到文件变化，但diff/blame仅聚焦textContent的差异，符合需求
• 团队协作时需将脚本纳入仓库，确保所有成员使用相同的过滤器配置
• 确保系统安装了Python3，避免脚本执行失败

内容的提问来源于stack exchange，提问作者Foghorn