本地Submodule提交缺失，切换分支遇Git报错如何修复？

切换至包含Submodule的分支时出现报错：

fatal: failed to unpack tree object shaxxx
error: submodule xxx could not be updated

执行git switch --recursive-submodules=false xxx成功切换分支后，进入Submodule目录运行git pull origin xxx，但git log看不到该Submodule分支的最新提交，origin/xxx仍显示旧提交。新克隆的仓库可正常显示远程最新提交，说明问题出在当前本地仓库状态。尝试git submodule update --force --recursive --init --remote后，Submodule仍指向旧SHA，未拉取GitHub上的更新，执行git log origin/xxx也看不到远程最新提交。

1. 刷新Submodule的远程索引 #

进入Submodule目录，先手动同步远程仓库的最新索引，确保本地的origin引用是最新的：

cd path/to/submodule/xxx
git fetch origin

执行完再跑git log origin/xxx，应该就能看到远程的最新提交了。

2. 重置Submodule到远程分支最新状态 #

如果fetch后本地分支没同步，直接把当前分支重置到远程分支的最新提交：

git reset --hard origin/xxx

⚠️ 注意：这个命令会丢弃Submodule目录下所有未提交的修改，执行前确认不需要保留本地更改。

3. 同步主仓库的Submodule SHA记录 #

回到主仓库根目录，更新主仓库中Submodule的SHA记录，让它和当前Submodule的HEAD一致：

cd ../.. # 回到主仓库根目录
git add path/to/submodule/xxx
git commit -m "Update submodule xxx to latest commit"

如果只是要本地状态匹配，不需要提交的话，可以跳过commit步骤。

4. 彻底重置Submodule（以上步骤无效时用） #

如果前面的方法都没解决问题，直接清空Submodule的本地缓存，重新初始化：

1. 从主仓库移除Submodule的缓存：

git submodule deinit -f path/to/submodule/xxx

2. 删除Submodule的本地目录：

rm -rf path/to/submodule/xxx

3. 重新初始化并拉取Submodule：

git submodule update --init --recursive path/to/submodule/xxx

这一步会重新从远程克隆Submodule，效果和新克隆仓库类似，但能保留主仓库的其他本地修改。

5. 验证修复结果 #

完成后，检查以下内容确认修复成功：

• 在Submodule目录执行git log --oneline，确认显示远程最新提交
• 在主仓库执行git submodule status，确认Submodule的SHA和远程分支的HEAD一致

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