快速理解 Git submodule

一句话理解

submodule = 在一个 Git 仓库里，引用另一个 Git 仓库的某个提交。

也就是说：
• 主仓库不直接“吃进去”另一个仓库的全部历史
• 而是记录那个子仓库当前指向的 commit
• 别人拉主仓库时，也能把这个子仓库一起拉下来

你可以把它理解成：主项目里“挂载”了另一个独立维护的仓库，主仓库只会记录其commit。

它解决什么问题

常见场景：
• 你的项目依赖一个独立组件，但你不想把代码直接复制进来
• 多个项目共用同一个库
• 需要固定依赖在某个版本，而不是总跟着最新代码跑

submodule 和直接拷贝代码的区别

直接拷贝代码：
• 简单
• 但后续同步更新麻烦
• 容易改乱来源

用 submodule：
• 子仓库仍然是独立 Git 仓库
• 有自己的提交历史
• 主仓库只记录“我现在依赖它的哪个 commit”

最核心的认知

1. submodule 不是普通文件夹

它里面其实是另一个 Git 仓库。

2. 主仓库记录的是子仓库的 commit 指针

不是自动跟着子仓库最新分支走。

3. clone 主仓库时，submodule 默认不会自动完整拉下来

需要额外初始化

常用操作命令

1. 添加submodule
   git submodule add

示例：
git submodule add https://github.com/example/shared-lib.git libs/shared-lib

命令会生成两个文件：

• gitmodules: 记录submodule的地址和路径
• libs/shared-lib: 子模块入口

2. clone/初始化项目
   第一次 clone 项目，submodule 是空的，需要初始化子模块：
   git submodule update --init --recursive

–recursive 表示如果子模块里还有子模块，也一并处理。

3. 查看submdule 状态
   git submodule status

4. 更新/同步 submodule
   git submodule update --init --recursive