详解git submodule HEAD detached 的问题

发布日期： 2026-01-12 阅读量： 作者： 用户投稿

在使用git submodule 的时候，常常会遇到执行完以下操作后发现子仓库的head 指针处于游离状态

然后切换到子仓库，查看当前分支的状态如下

原因是之前同事在子仓库中修改并提交后，没有在父仓库中更新子仓库的最新提交记录
正常情况下，修改子仓库的内容并在子仓库提交后会在父仓库执行 git diff会有如下输出

解决git submodule head detached的方法：

重新建立submodule，加入时使用-b参数，使得母项目追踪子项目的指定branch（否则默认不追踪）：

git submodule add -b <branch> <repository> [<submodule-path>]
git submodule update --remote

简单的一行命令递归修复所有子项目的detached head（其中默认都追踪子项目的master branch）：

git submodule foreach -q --recursive 'git checkout $(git config -f $toplevel/.gitmodules submodule.$name.branch || echo master)'

参考

Why is my Git Submodule HEAD detached from master?
Git submodules best practices

随便看看