Git submodule更新后出现detached HEAD警告、常规修复无效该如何处理

问题根因 #

• 主项目对submodule的版本记录，本质是存储一个固定的子模块commit哈希值，不是实时追踪子模块远程分支的最新提交。之前手动进子模块目录pull到v3的操作，是在子模块默认的detached HEAD状态下拉的提交，没有把这个新commit绑定为可被主项目关联的有效版本，所以才会同时触发「主项目提示子模块有新提交」和「提交时detached HEAD警告」两个问题。
• 之前在子模块目录建临时分支做切换的操作没解决问题，核心原因是操作只改了子模块内部的本地分支状态，没有把子模块当前指向的v3 commit回写到主项目的版本记录里，主项目的索引还是存的旧的v2版本关联，自然识别不到你要的变更。
• 重新执行git submodule update导致子模块回退v2，是这个命令的固有逻辑：它的作用就是把工作区的子模块状态，完全对齐到主项目git索引里存的旧commit（也就是v2的哈希），自然会把你手动拉的v3变更覆盖掉。
• 执行git submodule update --remote --merge/rebase没生效，一般是本地主项目的.gitmodules配置里，子模块追踪的远程分支和实际存v3的master分支不匹配，或者本地缓存的子模块远程引用过期，导致命令根本拉不到目标的v3版本。

修复操作步骤 #

1. 回到主项目工作根目录，切到日常开发的develop分支，同步远程最新状态，确保没有本地没提交的主项目变更干扰操作：

   git checkout develop
   git pull origin develop
   

2. 重置并同步子模块的全局配置，清掉本地过期的子模块缓存：

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

   这一步跑完子模块会回到主项目记录的v2状态，是正常现象，不用慌。
3. 进入子模块目录，拉取子模块远程仓库的最新提交，切到实际存v3版本的master分支，让子模块脱离detached HEAD状态：

   cd shared-module
   git fetch origin
   git checkout master
   git pull origin master
   

   跑完这一步，子模块就处于正常的分支跟踪状态，工作区代码就是v3版本。如果这一步提示本地修改冲突，先执行git stash暂存本地未提交的修改再继续。
4. 回到主项目根目录，检查状态确认没有detached HEAD警告：

   cd ..
   git status
   

   这时候主项目的git索引会正确识别子模块指向的v3 commit，关联关系是合法的，不会再触发detached HEAD报错。
5. 把子模块的版本变更暂存、提交，推送到主项目的develop分支，完成整个升级流程：

   git add shared-module
   git commit -m "chore: upgrade shared-module from v2 to v3"
   git push origin develop
   

避坑提醒 #

• 平时操作别在子模块的detached HEAD状态下拉完代码就直接回主项目提交：只要子模块当前没绑定到本地跟踪分支，哪怕代码内容全对，git也会抛detached HEAD警告。正确流程永远是先在子模块目录切到对应跟踪分支、对齐版本后，再回主项目提交关联变更。
• 别搞混git submodule update的作用：这个命令只用来对齐主项目记录的子模块版本，要拉子模块远程分支的最新代码，要么进子模块目录手动pull，要么明确指定追踪分支参数执行git submodule update --remote。
• 如果后续要长期让主项目的子模块自动追踪对应分支的最新版本，可以在.gitmodules里给对应子模块配置指定追踪的分支（比如branch = master），之后跑远程更新就不会出现分支不匹配的问题。

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