Git 子模块使用教程：添加、更新与删除

在 Git 版本控制中，Git 子模块允许你将一个仓库作为另一个仓库的子目录进行管理，同时保持两者的独立版本历史。这种机制在管理依赖库或共享组件时非常有用，但操作不当容易引发混乱。本文将从实际操作出发，讲解添加、更新与删除子模块的完整流程，并指出常见误区。

添加子模块

添加子模块的典型场景是：你的项目需要引入某个外部仓库，并固定其版本。使用 git submodule add 命令即可完成添加，例如：

git submodule add https://github.com/example/lib.git lib

执行后，Git 会将该仓库克隆到指定目录，并在主仓库中记录子模块的提交 ID。此时，主仓库的 .gitmodules 文件会记录子模块的路径和 URL，而子模块目录本身则处于“未跟踪”状态。

需要注意的是，子模块的添加仅记录当前提交的引用，并不会自动跟踪子模块的最新更改。这意味着，如果子模块仓库有新的提交，主仓库不会自动感知，除非你显式更新。

更新子模块是常见的需求，但操作方式取决于你的目标。以下是几种常见场景：

进入子模块目录，拉取远程更新并检出目标分支：

cd lib
git pull origin main

然后回到主仓库，将子模块的新提交记录到主仓库中：

cd ..
git add lib
git commit -m "Update lib to latest"

使用 git submodule update --remote 可以一次性将所有子模块更新到各自远程仓库的默认分支（通常是 master 或 main），但该命令不会改变主仓库记录的提交，除非你手动提交。

git submodule update --remote

之后，你需要检查子模块的状态并提交更改。

边界条件：如果子模块的远程分支与本地不一致，或者子模块存在未提交的本地修改，更新可能会失败。此时，需要先处理本地冲突或使用 git submodule update --force 强制更新（注意会丢失本地修改）。

删除子模块比添加更复杂，需要清理多个位置。步骤如下：

git config -f .gitmodules --remove-section submodule.lib

git config --remove-section submodule.lib

git rm --cached lib

rm -rf lib

git commit -m "Remove submodule lib"

最后，还需要删除 .git/modules/lib 目录（如果存在），以清理残留的 Git 数据。

如前所述，子模块的提交 ID 是固定的。如果你在子模块中修改了代码，但未在主仓库中提交新的引用，其他协作者克隆主仓库时，会得到旧版本的子模块。

直接删除目录会导致主仓库状态不一致，必须按照上述步骤完整清理。

如果子模块的远程仓库 URL 失效或需要权限，克隆主仓库时子模块初始化会失败。此时，可以尝试使用 git submodule update --init --recursive 并检查网络或凭据。

本文参考了以下权威文档：

延伸阅读