Git Submodule

Wed, 22 Jul 2026 20:54:40 +0800

Git Submodule：原理与协作流程

git submodule 将一个独立 Git 仓库挂载到另一个仓库的工作树中。被挂载的仓库称为 submodule，外层仓库称为 superproject。父仓库记录的不是子模块文件副本或分支名，而是子仓库的某个提交 ID。

本文以 Git 官方文档 gitsubmodules 为准，使用一个最小的 app 与 libfoo 仓库示例说明其工作原理、日常操作和适用边界。

工作树（working tree） 是当前 commit 被检出到文件系统中的文件集合，也就是用户实际查看和修改的目录。它与暂存区和 Git 元数据目录不同：

TEXT

工作树 -- git add --> 暂存区（.git/index）
暂存区 -- git commit -> 提交对象（.git/objects/）

例如，third_party/libfoo 是 submodule 的工作树；该目录中的文件可以被编辑，但它们的提交历史、索引和对象保存在对应的 Git 目录中。

设主仓库为 app，其中有一个子模块 third_party/libfoo。它们是两个相互独立的仓库：

TEXT

app (superproject，父仓库)
├── .gitmodules # 受版本控制的子模块声明
├── src/
└── third_party/libfoo # submodule 工作树，也是独立 Git 仓库
 └── ...

父仓库的一个提交中，third_party/libfoo 对应的树项模式是 160000，Git 称它为 gitlink。其对象 ID 是子仓库的 commit ID，例如：