详解git submodule HEAD detached 的问题

详解git submodule HEAD detached 的问题

问题描述

在使用 Git 进行子模块管理时，可能会出现 HEAD detached 的问题，即子模块处于分离头状态，此时操作会受到限制，比如无法直接修改代码等。

问题原因

在父仓库中，子模块仅仅是被引用，而非实实在在的代码，Git 仅管理子模块仓库的引用版本号。在引用时，默认选择该子模块仓库的特定 commit 时，便会出现 HEAD detached 的情况。

解决方案

问题的解决方案是确保子模块处于一个分支上，而非对于某个 commit 进行引用。采取以下步骤解决该问题：

1. 进入子模块目录，分支切换到父仓库所需要的版本：

$ cd ./path/to/your/submodule
$ git checkout master
$ git pull

1. 返回父仓库，将子模块仓库的版本信息保存：

$ cd ..
$ git add ./path/to/your/submodule
$ git commit -m "Update submodule to latest version"

1. 推送更改到远端仓库：

$ git push

从此，再对子模块操作等流程都将变得方便。当然，在我们正式执行这三步的时候，有些问题预先需要注意和处理。

注意事项

1. 避免在父仓库在切换版本时使用不当，会破坏子模块所在的 repo 的 HEAD 状态。正确从远端仓库拉取代码，或为其创建分支。

2. 如果在子模块里出现了分支，则切换分支后也需在父仓库中更新 commit 信息。

示例说明

示例一

# clone 一个仓库，其中包含子模块的引用
$ git clone [e-mail]:user/repo.git

# 初始化子模块，但存在 HEAD detached 问题
$ cd ./repo
$ git submodule update --init
$ cd ./path/to/your/submodule
$ git status

# 强制更改模块为一个新的分支名
$ git checkout master
$ git pull
$ git checkout -b new_branch_name
$ cd ..
$ git add ./path/to/your/submodule
$ git commit -m "Update submodule to latest version"
$ git push

示例二

# 对子模块进行 clone 或者更改操作
$ cd ./path/to/your/submodule
$ git checkout -b new_branch_name
$ git add filename
$ git commit -m "Create new file"
$ git push

# 在父仓库下，触发重新记录提交，使子模块的引用指向新的提交指针
$ cd ..
$ git add ./path/to/your/submodule
$ git commit -m "Update submodule to latest version"
$ git push

结论

当 Git 子模块状态出现 HEAD detached 问题，主要是因为 git submodule 默认情况下使用了 git checkout 命令，并不是保持子模块的状态为分支，这不利于我们后续的使用，将我们的开发限制在一个井号下，限制了我们对于这份代码作出任何修改。我们需要将子模块仓库变为普通的 Git 仓库，并从父仓库里引用，并将提交指针转移到一个将要保存的的分支上。