HOWTO · Git

拉取最新的 Git 子模块

在本文中,我们将介绍 Git 子模块。

本页内容

Git 子模块是在父仓库中检出的独立仓库。父仓库记录了子模块的一个特定提交,因此“更新”可能指恢复到这个已记录的提交,也可能指将子模块切换到远程仓库中的较新提交。在父仓库中运行 git submodule update --init --recursive,可初始化尚未初始化的子模块,并检出父仓库记录的提交。若要跟随较新的远程跟踪提交,则运行 git submodule update --remote --recursive;随后检查父仓库中发生变化的子模块指针,并提交该更改。

Git 子模块更新的工作方式

子模块拥有自己的提交历史和远程仓库配置。父仓库保存一个 gitlink,也就是指向嵌套仓库中某个提交的引用。因此,克隆或检出父仓库并不意味着子模块目录已经填充内容,也不意味着子模块会跟随远程分支的最新提交。

git submodule update 会检出当前父提交所记录的提交。如果你想使用项目声明的依赖版本,这是可复现的选择。--init 选项会注册并初始化 .gitmodules 中描述的子模块;--recursive 还会对嵌套子模块执行该操作。这些选项并不表示“获取最新提交”。

将子模块初始化并更新到记录的提交

如果刚克隆仓库时没有初始化子模块,或者检出了包含子模块的父提交,请在父仓库根目录运行:

git submodule update --init --recursive

Git 会按需初始化已配置的路径,并检出父仓库记录的各个提交。如果子模块已经初始化,该命令仍会将其工作树切换到记录的提交。检出后,子模块可能处于分离头指针状态;对于由父仓库固定到某个提交的子模块,这是正常现象。要查看哪些子模块指针与父仓库当前提交不同,请在父仓库中检查 git status。

获取子模块的较新远程提交

若要根据已配置的远程跟踪分支更新子模块,请在父仓库中运行 git submodule update --remote --recursive。Git 会从已配置的远程仓库获取数据,并检出由子模块所配置分支选定的提交。如果没有为某个子模块指定分支,Git 会使用其远程仓库的默认分支。这并不保证能获得所有分支或远程仓库中的最新提交;结果取决于已配置的分支及其已获取的远程跟踪状态。

远程更新会改变子模块当前检出的提交,并使父仓库显示子模块指针已修改。提交之前请先检查该更改。如果你只想获取远程数据而不改变当前检出的提交,请在子模块内执行获取操作并检查其分支;不要把 --remote 当作只获取数据的操作,因为它也会切换检出提交。

克隆包含子模块的仓库

若要在克隆仓库时一步递归初始化其中的子模块,请使用 git clone --recurse-submodules <repository-url>。将占位符替换为仓库 URL。普通的 git clone <repository-url> 会克隆父仓库,但不会初始化子模块工作树;若已用普通方式克隆,请进入新克隆的父仓库目录,再运行 git submodule update --init --recursive。

递归选项也会初始化嵌套在其他子模块中的子模块。检出时会使用克隆得到的父仓库所记录的提交;如果你需要项目选定的版本,这种方式就很合适。

提交并推送子模块更改

如果你在子模块内进行了更改,应先在子模块仓库中提交并推送。检出到父仓库固定的提交时,子模块可能处于分离头指针状态,因此发布更改前要选定目标远程分支。如果更改应属于现有分支,请切换到该分支并在那里整合更改;否则,为其创建一个分支。检查子模块的远程仓库和分支配置,并确认这是协作者应该使用的分支。然后用 git add 和 git commit 提交更改,再推送该分支,例如运行 git push <remote> <branch>。如果你有意保持 HEAD 处于分离状态,可以用 git push <remote> HEAD:<branch> 明确推送当前提交,并将占位符替换为选定的远程仓库和目标分支。请确保协作者获取父仓库时能够取得已推送的提交。

只有在子模块提交已发布后,才返回父仓库。父仓库的状态会显示子模块指针已更改;暂存该路径并提交父仓库,例如运行 git add path/to/submodule,然后运行 git commit -m "Update submodule pointer"。之后照常单独推送父仓库的提交。父提交记录新的子模块提交 ID,而子模块提交本身属于嵌套仓库。只推送父仓库,不会发布尚未推送的子模块提交;只推送子模块,也不会改变父仓库记录的提交。