重写Git仓库历史过程中替换二进制文件的方法咨询

核心结论 #

git filter-repo的--replace-text参数仅支持文本内容替换，无法处理二进制文件的匹配替换需求，你需要使用--blob-callback参数实现二进制文件的全历史替换，该方案不会修改任何原有提交的元信息（提交信息、作者、时间戳、提交树结构均完全保留）。

前置准备 #

• 提前对原始仓库做完整异地备份，避免操作失误丢失数据
• 安装最新稳定版git-filter-repo
• 提前调试好对应压缩文件的解压脚本/命令，确认解压后的内容完整性

全历史二进制文件替换 #

使用git filter-repo的blob回调功能遍历所有提交的文件对象，对匹配到的目标压缩文件自动做解压替换：

git filter-repo --blob-callback '
# 匹配规则可根据你的实际需求调整，以下为按文件后缀匹配示例
if blob.filename.endswith(b".custom_z"):
    import tempfile, os, subprocess
    # 写入临时压缩文件
    with tempfile.NamedTemporaryFile(suffix=b".custom_z", delete=False) as f:
        f.write(blob.data)
        temp_in_path = f.name
    temp_out_path = temp_in_path + b".unpacked"
    # 调用你自己的解压命令，替换为实际的解压程序路径和参数
    subprocess.run(
        ["/path/to/your/decompress_tool", temp_in_path, temp_out_path],
        check=True,
        capture_output=True
    )
    # 用解压后的内容替换原文件对象内容
    with open(temp_out_path, "rb") as f:
        blob.data = f.read()
    # 清理临时文件
    os.unlink(temp_in_path)
    os.unlink(temp_out_path)
'

如果你的压缩文件没有固定后缀，可以通过文件头魔数匹配，示例：

# 替换上面的文件名匹配逻辑，魔数根据你的压缩文件实际头4字节调整
if blob.data[:4] == b"CUST":

结果校验 #

• 执行git log --oneline核对提交历史和提交信息和原仓库完全一致
• 随机检出多个历史版本的对应文件，验证解压后的内容完整可用
• 检查仓库大小，确认替换后未压缩的二进制文件总大小符合预期

最终LZMA打包 #

处理完成后先清理git冗余对象，再执行LZMA打包：

# 深度清理仓库冗余对象
git gc --aggressive --prune=all
# 全目录LZMA压缩
tar -c --lzma -f archived_repo.tar.lzma /path/to/processed/repo

• 回调内所有文件名、内容都是bytes类型，不要直接和str类型字符串做匹配，避免编码错误
• 如果需要修改解压后的文件后缀，可在回调内增加blob.filename = blob.filename.replace(b".custom_z", b".raw")逻辑
• 解压命令执行时建议加上capture_output=True避免多余输出干扰进度展示

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