Git submodule未使用指定分支、始终检出旧提交该如何解决？

问题核心原因 #

Git 子模块的设计逻辑默认是与父仓库记录的特定提交哈希绑定的，.gitmodules 中配置的 branch 字段不会在默认克隆、更新子模块时自动生效，这就是你会遇到分离头指针状态、GitHub 显示子模块绑定固定哈希的根本原因。
另外你本地的 .git/config 中没有同步到子模块的分支配置，也会导致 --remote 参数无法正确拉取对应分支内容。

操作步骤 #

1. 同步子模块配置到本地 #

先将 .gitmodules 中的所有配置同步到本地仓库的 .git/config 中：

git submodule sync --recursive

2. 拉取对应分支最新提交并切换到分支 #

执行以下命令批量拉取所有子模块对应分支的最新提交，同时切换到对应分支而非分离头状态：

# 拉取各子模块配置分支的最新提交，合并到本地
git submodule update --init --recursive --remote --merge

# 批量切换所有子模块到配置的对应分支
git submodule foreach 'git checkout $sm_branch && git pull'

如果批量切换命令不生效，也可以单独进入对应子模块目录手动切换分支，比如 cd repo-web && git checkout task/test_install。

3. （可选）更新父仓库的子模块指针 #

如果你需要让其他协作者拉取到最新的子模块版本，需要在父仓库提交子模块的指针变更：

# 替换为你实际的子模块路径
git add repo-web report-templates Project-python
git commit -m "update submodules to latest branch commit"
git push

后续使用注意事项 #

• 直接执行 git clone --recursive 永远只会拉取父仓库当前记录的子模块固定提交，必然是分离头状态，拉取完成后需要执行上述步骤2的命令才能切换到对应分支
• 后续需要更新子模块到对应分支最新版本时，直接执行 git submodule update --recursive --remote --merge 即可

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