跳到主要内容

Git 子模块

子模块（Submodule）允许你将一个 Git 仓库作为另一个 Git 仓库的子目录。这在管理项目依赖、复用公共代码、模块化大型项目时非常有用。然而，子模块也是 Git 中最容易让人困惑的功能之一，理解其工作原理对于正确使用至关重要。

为什么需要子模块？​

在实际开发中，经常会遇到以下场景：

  • 引用外部依赖库：项目依赖某个第三方库，需要使用特定版本
  • 复用公共代码：多个项目需要共享同一套工具库或组件
  • 模块化大型项目：将大型项目拆分成独立的模块，分别开发和维护

如果没有子模块，你可能会：

  1. 直接复制代码到项目中——难以获取上游更新
  2. 使用包管理器——不适用于所有语言和场景
  3. 使用软链接——在跨平台时有问题

子模块提供了一种优雅的解决方案：在父仓库中记录子仓库的特定提交，而不是复制代码。

子模块的工作原理​

理解子模块的核心概念是正确使用它的关键。

父仓库存储的是什么？​

父仓库并不存储子模块的代码，而是存储：

  1. 子模块的 URL：存储在 .gitmodules 文件中
  2. 子模块的路径：子模块在父仓库中的目录位置
  3. 特定提交的引用：子模块当前指向的提交哈希

这个设计有几个重要含义：

  1. 版本锁定：父仓库明确记录子模块使用的确切版本
  2. 不会自动更新：子模块不会随上游更新而改变，需要手动更新
  3. 独立管理：子模块是一个独立的 Git 仓库，有自己的历史记录

.gitmodules 文件​

添加子模块后，会在项目根目录创建 .gitmodules 文件：

[submodule "libs/lib"]
    path = libs/lib
    url = https://github.com/example/lib.git

如果有多个子模块，文件会有多个条目：

[submodule "libs/lib"]
    path = libs/lib
    url = https://github.com/example/lib.git

[submodule "libs/utils"]
    path = libs/utils
    url = https://github.com/example/utils.git
    branch = stable    # 可选：指定要跟踪的分支

重要：.gitmodules 文件应该提交到版本控制，这样其他开发者才能知道子模块的来源。

Git 如何看待子模块目录​

父仓库中子模块目录的文件模式是 160000，这是 Git 的特殊模式，表示这是一个 Gitlink（子模块引用）：

$ git ls-files --stage libs/lib
160000 commit a1b2c3d4e5f6... libs/lib

这意味着 Git 不会跟踪子模块内部的文件变化，只跟踪子模块指向的提交。

添加子模块​

基本添加​

# 基本语法
git submodule add <repository-url> <path>

# 示例：添加子模块到 libs/lib 目录
git submodule add https://github.com/example/lib.git libs/lib

执行后会：

  1. 在 .gitmodules 中添加配置
  2. 克隆子模块仓库到指定目录
  3. 将 .gitmodules 和子模块引用添加到暂存区

添加时指定分支​

默认情况下，子模块处于"分离 HEAD"状态（指向特定提交）。你可以指定要跟踪的分支：

# 添加子模块并指定跟踪分支
git submodule add -b main https://github.com/example/lib.git libs/lib

# 这会在 .gitmodules 中添加 branch = main

添加时指定名称​

如果一个仓库需要作为多个子模块添加，可以通过名称区分：

# 添加同名仓库的不同分支作为不同子模块
git submodule add --name lib-v1 https://github.com/example/lib.git libs/lib-v1
git submodule add --name lib-v2 https://github.com/example/lib.git libs/lib-v2

克隆包含子模块的仓库​

这是新手最容易遇到问题的地方。普通克隆只会创建空的子模块目录。

方法一：递归克隆（推荐）​

# 克隆时自动初始化和更新所有子模块
git clone --recurse-submodules https://github.com/example/project.git

递归克隆示意图：

方法二：克隆后初始化​

如果忘记使用 --recurse-submodules，可以手动初始化：

# 克隆仓库
git clone https://github.com/example/project.git
cd project

# 初始化子模块配置
git submodule init

# 更新子模块（下载代码）
git submodule update

# 或者合并为一步
git submodule update --init

分步克隆示意图：

处理嵌套子模块​

如果子模块还包含子模块，需要使用 --recursive 选项：

# 递归初始化和更新所有嵌套子模块
git submodule update --init --recursive

# 或在克隆时
git clone --recurse-submodules https://github.com/example/project.git

更新子模块​

理解子模块的更新机制​

子模块的"更新"有两种含义：

  1. 检出父仓库记录的提交：git submodule update
  2. 获取子模块上游的最新提交：git submodule update --remote

这两种操作的目标不同，容易混淆。

检出父仓库记录的提交​

当父仓库的子模块引用发生变化时（比如有人更新了子模块版本），你需要更新本地：

# 更新所有子模块到父仓库记录的提交
git submodule update

# 更新特定子模块
git submodule update libs/lib

# 更新并初始化（如果需要）
git submodule update --init

关键理解：这个命令不会从子模块的远程获取新代码，只是将本地子模块检出到父仓库记录的那个提交。

获取子模块上游的更新​

如果你想更新子模块到其远程仓库的最新版本：

# 获取子模块远程的最新提交，并更新到默认分支
git submodule update --remote

# 更新特定子模块
git submodule update --remote libs/lib

# 获取后合并到当前分支
git submodule update --remote --merge

# 获取后变基到当前分支
git submodule update --remote --rebase

执行 --remote 后，子模块会更新到远程分支的最新提交，同时父仓库会记录这个变化。你需要提交这个变化：

# 查看变化
git status
# 会显示：modified: libs/lib (new commits)

# 提交子模块版本更新
git add libs/lib
git commit -m "chore: 更新 lib 子模块到最新版本"

手动更新子模块​

你也可以进入子模块目录手动操作：

# 进入子模块目录
cd libs/lib

# 获取远程更新
git fetch origin

# 切换到目标分支
git checkout main

# 拉取最新代码
git pull origin main

# 返回父仓库
cd ../..

# 提交子模块引用的变化
git add libs/lib
git commit -m "chore: 更新 lib 子模块"

在子模块中工作​

如果你需要在子模块中开发：

# 进入子模块
cd libs/lib

# 确保在一个分支上工作（避免分离 HEAD）
git checkout main

# 创建功能分支
git checkout -b feature/new-feature

# 开发并提交
git add .
git commit -m "feat: 添加新功能"

# 推送到子模块远程
git push origin feature/new-feature

# 返回父仓库
cd ../..

# 提交子模块的引用变化
git add libs/lib
git commit -m "chore: 更新 lib 子模块引用"

在团队中使用子模块​

拉取包含子模块更新的代码​

当团队成员更新了子模块版本后，你拉取代码时需要特别注意：

# 拉取父仓库更新
git pull

# 这时子模块目录可能显示 "new commits"
git status
# modified: libs/lib (new commits)

# 更新子模块
git submodule update

# 或者一步完成（Git 2.14+）
git pull --recurse-submodules

推荐配置：自动更新子模块

# 配置 git pull 时自动更新子模块
git config submodule.recurse true

# 或配置特定命令的行为
git config pull.recurseSubmodules on-demand

推送包含子模块更新的代码​

推送时需要确保子模块的更改也已推送：

# 方法一：检查子模块是否都已推送
git push --recurse-submodules=check

# 如果有未推送的子模块提交，会提示：
# The following submodule paths contain changes that cannot be found on any remote:
#   libs/lib
# Please try git push --recurse-submodules=on-demand

# 方法二：自动推送子模块（推荐）
git push --recurse-submodules=on-demand

推荐配置：

# 配置默认行为
git config push.recurseSubmodules on-demand

合并子模块冲突​

当两个人同时更新子模块到不同版本时，会产生冲突：

# 合并时可能出现
CONFLICT (submodule): Merge conflict in libs/lib

# 查看冲突
git diff
# -Subproject commit a1b2c3d
# +Subproject commit d4e5f6g

解决方法：

# 方法一：选择其中一个版本
git checkout --ours libs/lib      # 使用我们的版本
git checkout --theirs libs/lib    # 使用他们的版本

# 方法二：使用特定提交
cd libs/lib
git checkout <commit-hash>
cd ../..
git add libs/lib

# 方法三：合并子模块内部的变更（如果可能）
cd libs/lib
# 找到两个提交的共同祖先，进行合并
git checkout a1b2c3d
git merge d4e5f6g
# 解决子模块内部的冲突
cd ../..
git add libs/lib

子模块常用命令​

查看子模块状态​

# 查看子模块状态
git submodule status

# 输出示例
 a1b2c3d libs/lib (v1.0.0)
+b2c3d4e libs/utils (heads/main)
-c3d4e5f libs/old (remotes/origin/main)

状态符号含义：

符号含义
（空格）子模块已检出，与父仓库记录一致
+子模块当前提交与父仓库记录不同
-子模块未初始化
U子模块有合并冲突

在所有子模块中执行命令​

# 在所有子模块中执行命令
git submodule foreach 'git status'

# 递归执行（包括嵌套子模块）
git submodule foreach --recursive 'git checkout main'

# 检查所有子模块是否有未提交的更改
git submodule foreach 'git diff --quiet || echo "有未提交的更改"'

同步子模块配置​

当 .gitmodules 中的 URL 发生变化时：

# 同步 .gitmodules 中的 URL 到本地配置
git submodule sync

# 递归同步
git submodule sync --recursive

吸收子模块的更改​

如果你在子模块中做了提交但还没推送，想把父仓库的引用指向新提交：

# 子模块中的更改会自动反映在 git status 中
# 只需添加并提交
git add libs/lib
git commit -m "chore: 更新子模块引用"

删除子模块​

删除子模块需要多个步骤，容易遗漏：

# 1. 反初始化子模块
git submodule deinit -f libs/lib

# 2. 从 .git/modules 中删除
rm -rf .git/modules/libs/lib

# 3. 从 .gitmodules 和暂存区移除
git rm -f libs/lib

# 4. 提交更改
git commit -m "chore: 移除 lib 子模块"

# 5. 如果 .gitmodules 文件变空，可以删除
rm .gitmodules
git rm .gitmodules
git commit -m "chore: 移除空的 .gitmodules 文件"

简化方式（Git 2.17+）：

# 使用 git rm 移除子模块
git rm libs/lib
git commit -m "chore: 移除 lib 子模块"

子模块常见问题与解决​

问题：子模块目录是空的​

原因：克隆时没有使用 --recurse-submodules 或没有执行 git submodule update。

解决：

git submodule update --init --recursive

问题：子模块处于分离 HEAD 状态​

原因：子模块默认检出到一个特定提交，不在任何分支上。

解决：

# 进入子模块目录
cd libs/lib

# 切换到需要的分支
git checkout main

# 如果之前有修改，可能需要创建新分支保存
git checkout -b my-work

问题：更新子模块后之前的修改丢失​

原因：在分离 HEAD 状态下做修改，git submodule update 后被覆盖。

解决：

  1. 使用 reflog 找回：
cd libs/lib
git reflog
# 找到之前的提交
git checkout <commit-hash>
git checkout -b recover-branch
  1. 预防：始终在分支上工作
# 进入子模块后，先切换到分支
cd libs/lib
git checkout main
# 然后再做修改

问题：推送失败，子模块提交未推送​

原因：父仓库记录的子模块提交在远程子模块仓库中不存在。

解决：

# 方法一：使用 --recurse-submodules=on-demand
git push --recurse-submodules=on-demand

# 方法二：手动推送子模块
cd libs/lib
git push origin main
cd ../..
git push

问题：子模块 URL 变化后无法更新​

原因：.gitmodules 中的 URL 变化了，但本地配置未更新。

解决：

# 同步 URL 到本地配置
git submodule sync --recursive

# 重新更新子模块
git submodule update --init --recursive

问题：克隆速度慢​

解决：使用浅克隆

# 克隆父仓库
git clone https://github.com/example/project.git

# 浅克隆子模块
git submodule update --init --depth 1

子模块 vs 其他方案​

子模块 vs 包管理器​

特性子模块包管理器
语言支持语言无关特定语言
版本控制Git 提交级别语义化版本
开发体验可直接编辑源码通常编译后
依赖管理手动管理自动解析依赖
适用场景需要修改依赖源码纯粹使用依赖

子模块 vs Git Subtree​

特性子模块Subtree
存储方式引用（不存储代码）合并（存储完整代码）
克隆速度需要额外步骤一步到位
管理复杂度较高较低
更新操作需要特殊命令普通合并
独立开发支持不太方便
仓库大小小大

选择建议​

使用子模块当：

  • 需要在多个项目中复用代码
  • 需要独立开发和版本化子项目
  • 子项目有独立的生命周期

使用包管理器当：

  • 有成熟的生态系统（npm、pip、cargo 等）
  • 不需要修改依赖源码
  • 需要依赖解析和版本约束

使用 Subtree 当：

  • 想要更简单的工作流
  • 需要一次性克隆所有代码
  • 子项目更新不频繁

最佳实践​

1. 始终指定分支​

# 添加子模块时指定分支
git submodule add -b main https://github.com/example/lib.git libs/lib

# 更新 .gitmodules
git config -f .gitmodules submodule.libs/lib.branch main

2. 使用别名简化命令​

# 添加常用别名
git config alias.su 'submodule update --init --recursive'
git config alias.ss 'submodule status'
git config alias.sf 'submodule foreach'

# 使用
git su   # 等同于 git submodule update --init --recursive

3. 配置自动更新​

# 拉取时自动更新子模块
git config submodule.recurse true

# 推送时检查子模块
git config push.recurseSubmodules check

4. 提交前检查​

# 创建钩子检查子模块状态
# .git/hooks/pre-commit
#!/bin/bash
if git submodule status | grep -q '^+'; then
    echo "有子模块未提交或未更新"
    exit 1
fi

5. 使用 Git 别名工作流​

# 在 .gitconfig 中添加
[alias]
    # 更新所有子模块
    subup = submodule update --init --recursive
    # 推送时检查子模块
    subpush = push --recurse-submodules=on-demand
    # 查看子模块状态
    substat = submodule status

命令速查表​

命令说明
git submodule add <url> <path>添加子模块
git submodule add -b <branch> <url> <path>添加子模块并指定分支
git submodule init初始化子模块配置
git submodule update更新子模块到父仓库记录的提交
git submodule update --init初始化并更新子模块
git submodule update --remote更新子模块到远程分支最新提交
git submodule update --remote --merge更新并合并
git submodule status查看子模块状态
git submodule foreach '<command>'在所有子模块执行命令
git submodule sync同步子模块 URL 配置
git submodule deinit -f <path>反初始化子模块
git clone --recurse-submodules <url>递归克隆
git pull --recurse-submodules拉取并更新子模块
git push --recurse-submodules=on-demand推送时自动推送子模块

小结​

本章我们学习了：

  1. 子模块的概念：父仓库存储子模块的提交引用，而非代码本身
  2. 添加和克隆：git submodule add 和 --recurse-submodules
  3. 更新机制：理解 update 和 update --remote 的区别
  4. 团队协作：推送、拉取、解决冲突的流程
  5. 常见问题：空目录、分离 HEAD、丢失修改等
  6. 最佳实践：指定分支、配置别名、自动化操作

子模块虽然功能强大，但使用复杂。在使用前，请评估是否有更简单的替代方案（如包管理器）。如果确实需要子模块，遵循最佳实践可以避免大多数问题。

练习​

  1. 创建一个项目，添加子模块，体验完整的工作流
  2. 模拟团队协作：两人同时更新子模块，解决冲突
  3. 练习在分离 HEAD 状态下的恢复操作
  4. 配置自动化工作流（recurseSubmodules、别名等）

参考资料​