Git子模块报错‘fatal: Unable to find refs/remotes/origin/HEAD’原因排查

问题原因 #

这个报错不是Git的bug，主要由以下几种情况导致：

• 子模块配置异常：项目根目录的.gitmodules文件中，Assets/NRSDK子模块的branch字段被设置为HEAD，或者未指定具体分支，导致Git尝试用origin/HEAD作为更新目标，但该引用无法被正确解析。
• 远程仓库HEAD引用缺失：远程仓库未设置默认分支，或者本地未拉取到origin/HEAD的引用（比如首次fetch时未获取该引用）。
• 子模块本地状态损坏：子模块的.git文件夹损坏，或远程URL配置错误，导致无法正确同步远程引用。

解决步骤 #

1. 检查并修正子模块分支配置
   查看项目根目录的.gitmodules文件中Assets/NRSDK的配置：

   cat .gitmodules | grep -A 5 "Assets/NRSDK"
   

   如果发现branch = HEAD或者没有branch字段，将其修改为远程仓库的实际默认分支（比如main或master）：

   [submodule "Assets/NRSDK"]
       path = Assets/NRSDK
       url = <子模块远程仓库URL>
       branch = main
   

2. 修复远程仓库HEAD引用
   进入子模块目录，同步远程仓库的HEAD引用：

   cd Assets/NRSDK
   git remote set-head origin -a
   

   这个命令会自动将origin/HEAD设置为远程仓库的默认分支。

3. 重新同步并更新子模块
   回到项目根目录，执行以下命令重新同步配置并更新子模块：

   git submodule sync --recursive
   git submodule update --init --remote --recursive
   

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