Git异常：工作树干净但git diff HEAD仍显示文件变更

现象描述 #

1. 基础状态验证显示工作树完全干净：

ruqi.shang@ 13:18 monorepo % git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean
ruqi.shang@ 13:24 monorepo % git diff --stat
ruqi.shang@ 13:25 monorepo % git diff --cached --stat

2. 执行git diff HEAD却误报两个文件被删除：

ruqi.shang@ 13:25 monorepo % git diff HEAD --stat
 npmrc.json   |    8 -
 package.json | 1062 -------------------------------------------------------------------------------------------------------------------------------------
 2 files changed, 1070 deletions(-)

3. 对比上一提交时同样出现该误报：

ruqi.shang@ 13:25 monorepo % git diff HEAD^ --stat
 1.java                 |    4 +
 2.java                 |   38 +-
 3.java                 |    8 +
 4.java                 |    8 +
 5.java                 |   58 +++
 ...
 npmrc.json             |    8 -
 package.json           | 1062 ------------------------------------------------
 10 files changed, 199 insertions(+), 1073 deletions(-)

4. 被误报删除的文件实际存在：

ruqi.shang@ 13:35 monorepo % ls -lah npmrc.json package.json
-rw-r--r--  1 ruqi.shang  staff   169B Sep 21 13:06 npmrc.json
-rw-r--r--  1 ruqi.shang  staff    35K Sep 21 13:06 package.json

5. 文件未被Git忽略：

ruqi.shang@ 13:41 monorepo % git check-ignore npmrc.json package.json
ruqi.shang@ 13:41 monorepo %

6. 单独指定这两个文件执行git diff HEAD时无变更：

ruqi.shang@ 13:44 monorepo % git diff HEAD -- npmrc.json package.json
ruqi.shang@ 13:44 monorepo %

已排查操作 #

• Git版本：git version 2.40.0（MacOS系统）
• 排除文件系统大小写问题：

ruqi.shang@ 11:25 monorepo % git ls-tree --name-only HEAD | grep -i package.json
package.json
ruqi.shang@ 11:25 monorepo % git ls-tree --name-only HEAD | grep -i npmrc.json
npmrc.json

• 刷新索引后状态仍显示干净：

ruqi.shang@ 13:50 monorepo % git ls-files -v package.json npmrc.json
H npmrc.json
H package.json
ruqi.shang@ 13:50 monorepo % git update-index --really-refresh package.json
ruqi.shang@ 13:50 monorepo % git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

问题原因及解决方案 #

这是Git 2.40.0版本的已知Bug：当仓库包含大文件（如你的package.json）或文件数量较多时，git diff遍历文件索引时会出现逻辑异常，导致误报文件删除。

解决方法：

1. 升级Git到2.41.0及以上版本，该版本已修复此索引对比Bug
2. 临时规避：执行git diff HEAD -- .代替git diff HEAD，明确指定对比当前目录所有文件，可绕过索引遍历异常

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