两份 PDF 在 git 里只显示 Binary files differ:用 OmniDiff 看清改了哪一页

23次阅读
没有评论

要核对两版 PDF、一张改过的截图,或一个发布用的 zip,常见结果是:git diff 或系统自带的比较只留下一句 “Binary files differ”。你知道文件变了,却看不到是哪一页、哪一块像素,或压缩包里的哪一个文件。

OmniDiff 是一个开源命令行工具(也有终端里的双栏界面),按内容来比较,而不是把所有文件都当成纯文本行。代码会尽量按语法结构来看;图片会报告改了多少像素、在哪个区域;PDF 会一页页画出来再比;zip、tar 一类压缩包则先展开,再按里面每个文件自己的类型继续比。2026-11-13 我们在 Linux 上安装了正式版 v0.4.0,用四组自制小文件跑了 --headless 比较。Windows / macOS 安装包官方提供了,这次没有装。

适合谁、先看清什么

适合经常要看清“到底改了什么”、又会被二进制文件挡住的人:比如核对自动生成的 PDF 报表是不是只改了一个数字,检查设计稿或 UI 截图改在何处,或比较两个 release 压缩包里哪些成员变了。它也可以接进 Git 或 Jujutsu,当作 difftool;本次为了不改本机的 Git 配置,没有实际执行 omnidiff git configure。

它不是 Adobe Acrobat 里那种专业的 PDF 审阅批注,也不是 Word 里的“修订”。按仓库 README,Office 文档(docx / xlsx 等)是按 ZIP 容器、把内部文件逐个比较,不是页面预览上的红线修订。这一条我们没有拿 Word / Excel 实测。

许可证是 AGPL-3.0-only(不能直接套“以后的 AGPL 版本”)。个人和可以接受 AGPL 的使用是免费的;若公司内部无法接受 AGPL 的源码义务,作者提供单独的商业许可,走 GitHub Sponsors,条款见仓库里的 LICENSE-COMMERCIAL。本次没有打开 Sponsors 页面核对档位价格。

项目 情况(查阅并于 2026-11-13 部分实测)
仓库 https://github.com/ivankovic/omnidiff(查阅当日约 1355 star,Rust)
版本 正式版 v0.4.0(GitHub Release 时间为 2026-11-08)。本机安装后 omnidiff --version 为 omnidiff 0.4.0
平台 Releases 提供 Linux(gnu/musl,x86_64 与 ARM64)、macOS(Intel 与 Apple Silicon)、Windows x64;另有 .deb。本次只在 Linux x86_64 上装了 omnidiff_amd64.deb
用法 omnidiff 打开空的终端界面;omnidiff BEFORE AFTER 直接比较。--headless(或 stdout 不是终端时)输出纯文本;--mode json 输出一份 JSON,给编辑器集成
退出码 默认成功为 0、出错为 2。加上 --exit-code 时,两份文件有差异则返回 1,方便脚本和 CI。本次四组有差异的材料都是退出码 1
Showcase 官方演示页 是预先算好的回放,页上写明不是在线对比服务。下面的数字来自本机命令行,不是这个页面
两份 PDF 在 git 里只显示 Binary files differ:用 OmniDiff 看清改了哪一页
官方 Showcase 用预先录好的回放,对照 Unix diff 和 OmniDiff 对同一处 Python 重构的标法。这是项目自己的演示,不是本次自制材料(截图于 2026-11-13)

怎么安装、怎么比一份文件

  1. 到 Releases 下载对应系统的包。本次用的是 omnidiff_amd64.deb,SHA256 与发布页附带的 SHA256SUMS.txt 一致(aa18bcee…fcc5ed),再执行 sudo dpkg -i omnidiff_amd64.deb。也可以按 README 用官方 APT 源、Homebrew 或 cargo install --locked omnidiff,这三种本次没走。
  2. 跑 omnidiff --version,确认版本。再准备好要比较的两个路径,例如旧版 PDF 和新版 PDF。
  3. 若只要一份可以贴进工单或脚本的文本结果,执行:
omnidiff --headless --exit-code BEFORE AFTER

有差异时退出码是 1。需要给编辑器或后续程序用,就换成 omnidiff --mode json BEFORE AFTER。
4. 想在终端里交互着看,直接 omnidiff BEFORE AFTER(不要重定向输出)。图片、PDF 页和字体字形会画在界面里;本次没有截我们自己的 TUI,只核对了 headless 文本和 JSON。
5. 要把它接到 Git,官方入口是 omnidiff git configure。在没有配置之前,不要假设 git diff 会自动变成 OmniDiff。

README 还列出了 VS Code / Cursor / Windsurf 扩展和 jj 集成,本次都未安装。

我们实际比了四组小文件

测试时间是 2026-11-13,系统是 Linux x86_64。材料都是我们自己做的,没有用别人的文档或图片。

Python:不只是整段删除再新增

左边的 sum.py 用循环累加;右边改成 return sum(values),__main__ 部分相同。GNU diff -u 的结果是连续 4 行删除、1 行新增。OmniDiff 的 headless 输出把原来的 return result 标成更新(~),右侧写成 return sum(values),上面三行循环是删除,未改的 __main__ 被折叠。JSON 里 language 为 Python。对这个小例子来说,差别主要是标法更贴近“函数体被改成了一句”,而不是另一份完全不同的文件。更大的重构是否都好读,本次没有另做一套。

PDF:只改一个数字时,能报到页和区域

两份 PDF 由同一页 HTML 打出,只有银行账号最后一位从 0001 改成 0002。headless 输出是:

PDF, 2 members, 230447 bytes -> PDF, 2 members, 230448 bytes
1 changed, 0 added, 0 removed, 1 unchanged
changed page 1: 0.01% of pixels changed, in 1 region

JSON 写明第 1 页按 765×990 绘制,changed_pixels 为 44 / 共 757350 像素,区域在 (395, 472),大小 7×12,layout_kept 为 true。这和“只改了一个数字”相符。我们没有在 TUI 里打开看高亮图,所以不能把“区域坐标”写成已经用眼睛在界面上对过位置,只能说命令行给出的区域和改动幅度是合理的。

图片:能给出像素数量和坐标

把同一张 1020×1320 的 PNG 复制一份,再在 (720, 620) 处画了一个边长 12 的红块。OmniDiff 报:

0.01% of pixels changed (169 of 1346400), in 1 region:
13×13 at (720, 620)

坐标与绘制位置一致;169 大约是 13×13。文件体积从 99,321 字节变成 99,423 字节,若只看哈希或 diff,你只能知道它们不同。

压缩包:会打开成员再比

两个 zip 都只有 manifest.txt 和 readme.txt。前者从 version=1 改成 version=2,后者相同。输出为:

ZIP, 2 members, 246 bytes -> 2 members, 246 bytes
1 changed, 0 added, 0 removed, 1 unchanged
changed manifest.txt: 1 line removed, 1 added

两个压缩包体积一样,若只比较外层大小或“是不是 zip”,看不出差别。JSON 把这次变化记在 manifest.txt 上,未改的那个成员计为 unchanged。

本机耗时(仅供参考)

在同一台机器上,对上述四组各跑 5 次 omnidiff --headless,中位耗时大约是:Python 3.6 ms,PDF 45.5 ms,PNG 23.6 ms,ZIP 2.5 ms。这只是这几份小文件、这台电脑上的墙钟时间。仓库 README 另有一组 2026-11-07 在 Intel Core i7-1370P、2,302 条夹具上的统计(p50 4.4 ms 等),那是作者自己的测量环境,不能和上面的四个数字直接对比。

常见失败和限制

  • 没有对应解析器的文本(README 举例:Markdown、SQL、Dart、Protobuf 等)仍按普通行比较;没列进内容类型的二进制文件,最后仍可能只看到一句 Binary file differs。
  • Office 文档按压缩包内部文件来比,不要期待它长得像 Word 修订。本次未用 docx / xlsx 验证。
  • PDF 比较的是绘制后的像素。两个文件若只改了不可见的元数据或字体子集,结果可能是“看不见的差异”或很小的像素变化,需要结合 JSON 字段理解,不要只看百分比。
  • 默认退出码在“文件不同”时仍是 0,以免被 Git 一类工具当成命令失败。写脚本请加上 --exit-code。
  • AGPL 对网络服务和修改后再分发有源码义务。公司内部若不能接受,需要看商业许可,不要默认“开源就等于可以随便闭源集成”。
  • Windows、macOS、VS Code 扩展、Git / jj 接线,以及字体、光标、嵌套归档,本次都没有测。

和别的办法怎么选

只比较纯文本,系统自带的 diff -u 或编辑器自带的 diff 通常就够,也不用再学一套终端界面。已经在用 Git,只是偶尔被 PDF、图片挡住,OmniDiff 更像是补上这一块,而不是把整个 git diff 换掉。

若你的问题根本不是“两份文件差在哪里”,而是要把 PDF 合并、拆分、压缩,可以看站内的 pdf.iceai.cloud。若要在一份 PDF 上离线加批注,那是 PDF Tool。若要把合同里的手机号、账号从文件里真正去掉,再发给别人,那是打码,不是比较,可以看 AnyRedact。

小结

在这四组自制材料上,OmniDiff 0.4.0 都能给出比“Binary files differ”更具体的结果:Python 会标出被改写的返回值,PDF 和 PNG 能报到变化区域,zip 能指出是 manifest.txt 改了一行。它解决的是“看见改了哪里”,不是替你完成审阅或打码。安装和命令以当时的 Releases 与 README 为准。

正文完
 0
liujiana
版权声明:本站原创文章,由 liujiana 于2026-11-13发表,共计4108字。
转载说明:本文由(baffox.com)根据项目官网、开源社区及公开资料整理。工具的功能、价格、授权与服务条款可能随时间调整,请以官方最新页面为准。合理引用请注明出处并保留本页链接;如发现内容错误、版权或侵权问题,请通过联系邮箱进行反馈,我们将第一时间核实处理。
推广Baffox 推荐:搬瓦工 CN2 GIA 线路老牌 VPS推广Baffox 推荐:DMIT 香港 / 东京 / 洛杉矶高端线路 VPS
评论(没有评论)
验证码