git 仓库版本不兼容速查：unknown index entry format 的六个根因
更新时间：2026-10-24。FAQ 速查页，面向老机器上
git status直接报fatal: unknown index entry format 0x...、或新仓库克隆下来一堆git-lfs字样的几百字节小文件的同学。git 仓库版本不兼容的本质一句话：写仓库的 git 和读仓库的 git 不是一代人——新客户端写入的索引特性、仓库扩展、大文件指针，老客户端根本不认得，报错的措辞五花八门但病根都是版本差。收敛在六根轴上：索引文件的新特性标记老版本不认、仓库格式版本号与扩展字段升级、LFS 未安装导致大文件以指针文本落地、钩子与过滤器脚本依赖的工具缺失、团队新旧客户端混用互相制造不兼容、以及部分克隆等高级特性需要新版本支撑。本篇主线是「先分清楚是仓库格式不兼容还是辅助工具缺失」，两者的修法完全不同。
本文要回答的问题
unknown index entry format是仓库坏了还是 git 太老？core.repositoryformatversion是什么，能不能手动改回 0？- clone 下来的大文件只有一百多字节、内容是一段文本，是怎么回事？
unknown repository extensions found: objectformat怎么解？- 团队里有人用新版有人用发行版自带老版，怎么对齐？
一、报错原文与典型现象
版本不兼容家族的几种真实措辞如下（路径以 /proj/demo 占位）：
$ git -C /proj/demo status
fatal: unknown index entry format 0x74726965$ git -C /proj/demo status
fatal: unknown repository extensions found:
objectformat$ git -C /proj/demo log
warning: core.repositoryformatversion is 1; this version of git only supports version 0LFS 指针场景通常不报错，而是「静默翻车」——打开图片/压缩包发现是文本：
$ head -3 /proj/demo/assets/demo.zip
version https://git-lfs.github.com/spec/v1
oid sha256:4d7a2149ab8545c469b7a43837d8b5a5e1f04e2c26a3ee8e9d2c4a8f2c5a1b2c
size 1048576$ git -C /proj/demo checkout main
git-lfs filter-process: command not found
error: external filter 'git-lfs filter-process' failed读报错抓两个信号：报 unknown index entry format 或 repositoryformatversion 的，是仓库文件本身用了新版本特性，升级客户端是唯一正解；报 filter-process 或文件内容是指针文本的，是辅助工具没装，仓库格式没问题、装个 LFS 就好。混着治的典型空转：LFS 场景去升级 git——git 再新也不会自带 LFS。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| unknown index entry format | 老客户端不认新索引特性 | git --version 对比写入方版本 | 升级 git 到新版 |
| unknown repository extensions: objectformat | 仓库是 sha256 格式，老客户端只认 sha1 | 看 .git/config 的 extensions 段 | 升级到支持 sha256 的版本 |
| repositoryformatversion 超出版本支持 | 仓库格式版本被新特性抬高 | git config core.repositoryformatversion | 升级客户端，不回改配置 |
| 大文件内容是 version/oid/size 三行文本 | LFS 未安装，指针文件被当实体拉下 | 文件仅百余字节且含 oid 行 | 装 git-lfs 后 git lfs pull |
| git-lfs filter-process: command not found | 装了带 LFS 的仓库但本机无 lfs 命令 | git lfs version 报不存在 | 安装 git-lfs 并 git lfs install |
| 同一仓库 A 机能用 B 机报错 | 团队新旧客户端混用 | 两台机器分别 git --version | 统一最低版本基线 |
| partial clone 特性报不认 | --filter 克隆的仓库被老客户端打开 | 看 .git/config 的 promisor 配置 | 升级客户端或换全量克隆 |
| 钩子报错找不到某命令 | hooks 依赖的工具本机缺失 | 读 .git/hooks/ 报错对应脚本 | 装依赖或跳过钩子 |
三、排查决策图
下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓唯一的分水岭：报错指向「仓库格式」还是「外部工具」。格式层的病（index entry、repositoryformatversion、objectformat）只有升级客户端一味药；工具层的病（LFS、钩子依赖）装对应工具即解，仓库本身毫发无损。先分这一刀，再决定动哪边。
四、逐条排查展开
第一条：unknown index entry format——索引文件用了新特性。 索引（.git/index）是暂存区的二进制清单，新客户端会为性能写入扩展特性（如 track 内部状态的标记段），老版本解析器读到不认识的段头就直接 fatal。确认与处置：
git --version # 老机器常见是发行版自带的旧版
# 升级到当前稳定版后重跑 git status两个配套提醒：不要试图删 .git/index 绕过——索引重建会丢掉暂存状态，而且只要仓库里还有新特性来源（比如别人继续用新版写），问题会复发；也不要手动改索引格式配置，老老实实升级是唯一稳路。索引与暂存区的机制见 status、add、commit。
第二条：repositoryformatversion 与 extensions——仓库级格式升级。 .git/config 里的 core.repositoryformatversion 标仓库格式代数：0 是经典格式，1 表示启用了扩展段。扩展段里的 objectformat = sha256 意味着整个对象库用 SHA-256 哈希，只认 SHA-1 的老客户端打开就报 unknown repository extensions found。处置只有升级；红线是不要手动把 version 改回 0——扩展段对应的真实数据（sha256 对象）还在，改配置只会换来更诡异的损坏报错。团队要启用 sha256 仓库前，先确认所有人的客户端版本达标。
第三条：LFS 指针文件——不报错但「货不对板」。 仓库里的大文件（图片、压缩包、模型权重）走 LFS 管理时，版本库里存的只是百余字节的指针文本（version/oid/size 三行），实体存在 LFS 服务器，checkout 时由 git-lfs 过滤器换出真文件。本机没装 git-lfs 时，过滤器缺席，指针文本原样落盘——于是 zip 打不开、图片是碎的。标准处置：
git lfs version # 验证安装，报 command not found 就先装
git lfs install # 注册过滤器（每机器一次）
git lfs pull # 补齐当前仓库的 LFS 实体
file assets/demo.zip # 复验：输出应是 Zip archive 而非 ASCII text第四条：git-lfs filter-process: command not found——装了带 LFS 的仓库但没装 LFS。 这条是第三条的报错形态：checkout/clone 阶段过滤器被调用、命令不存在，直接 failed。处置同第三条：装 git-lfs、跑一次 git lfs install、再重跑 checkout。团队里引入 LFS 的决定必须配套「新人上手文档写前置安装」，否则每个新机器都要踩一次。
第五条：新旧客户端混用——版本基线不统一的慢性病。 A 机新版写入索引新特性，B 机老版打不开；B 机好不容易能用了，C 机的 CI 镜像又是另一个版本。治理靠基线：团队约定最低 git 版本（写在上手文档里），CI 镜像固定版本并定期滚动升级；个人机器上 git --version 低于基线就升。发行版自带源里的 git 普遍偏旧，Linux 用官方 PPA/源码、macOS 用 Homebrew、Windows 用官方安装包，都能拿到新版。多机配置的统一管理见 Git 配置、init 与 clone。
第六条：部分克隆与浅克隆的特性门槛。 git clone --filter=blob:none 这类部分克隆依赖较新的协议与客户端，克隆得到的仓库带 promisor 扩展配置，老客户端打开同样报 extensions 相关错误。处置一致：升级；或者对老环境换全量克隆。顺带一句：这类高级克隆姿势的取舍见 git clone 卡死超时速查——它们本是治大仓库传输的药，别因版本门槛在旧环境里反受其害。
五、规范做法与预防
- 团队版本基线：上手文档写明最低 git 版本与安装渠道，CI 镜像版本固定，低于基线的机器先升级再干活。
- LFS 前置声明：引入 LFS 的仓库在 README 写「先装 git-lfs 再 clone」，新人机器出问题先看大文件是不是指针文本。
- sha256 仓库先沟通：启用 objectformat=sha256 前全员确认客户端版本，老机器不硬开。
- 不回改格式配置：repositoryformatversion 与 extensions 段只读不写，格式问题一律升级客户端解决。
- 钩子依赖显式化：hooks 用到的外部命令在文档列清单，报错「command not found」时按单装齐。
这一篇在知识体系里的位置
本篇是 Git 排错速查簇的版本兼容篇，定位「写仓库的和读仓库的 git 不是一代人」：引用名找不到看 bad revision 引用找不到速查；中文文件名显示成转义串看 git 中文乱码速查；克隆与传输层的问题看 git clone 卡死超时速查；路径名不识别看 pathspec did not match 速查；配置体系的完整口径看 Git 配置、init 与 clone；认证与钥匙问题看 Permission denied (publickey) 速查。
一句话总结
git 仓库版本不兼容先按报错分两刀：指向仓库格式的（unknown index entry format、repositoryformatversion、objectformat 扩展）病根是老客户端不认新特性，唯一正解是升级 git、绝不手动回改格式配置；指向外部工具的（LFS 指针文本落地、git-lfs filter-process 找不到命令）病根是辅助工具缺失，装 git-lfs 后 git lfs install 加 git lfs pull 补齐实体。团队统一最低版本基线、LFS 仓库写明前置依赖、sha256 等格式升级先全员对版本，这类不兼容基本绝迹。