13、Git子模块与子树：git submodule、git subtree 的使用场景与区别
说到 Git 子模块和子树，我估计不少同学都踩过坑。我自己刚接触那会儿，也觉得这两个东西长得挺像——都是把别的仓库塞进自己的项目里嘛。但用起来才发现，它们完全是两码事。
今天咱们就把这两个工具掰开揉碎了讲清楚。什么时候该用 submodule，什么时候该用 subtree，以及它们各自有什么坑。
13.1 什么是 Git 子模块？
子模块，说白了就是「仓库里的仓库」。你可以在一个 Git 仓库里，引用另一个独立的 Git 仓库，并且锁定它的某个版本。
举个例子：你正在开发一个 Web 应用，里面用到了一个第三方主题库。这个主题库有自己的更新节奏，你不想把它直接复制到你的项目里，而是希望保持引用关系。这时候，子模块就派上用场了。
13.1.1 添加子模块
git submodule add https://github.com/example/theme.git themes/my-theme这条命令会做两件事：
- 把远程仓库克隆到
themes/my-theme目录下 - 在根目录生成一个
.gitmodules文件，记录子模块的信息
13.1.2 克隆带子模块的项目
如果你克隆一个包含子模块的项目，默认情况下子模块目录是空的。你需要额外执行：
git clone --recursive https://github.com/your/project.git或者克隆后再初始化：
git submodule init
git submodule update嗯，这里要注意：忘记初始化子模块 是我见过最频繁的翻车现场。团队成员拉完代码发现目录是空的，一脸懵。
13.1.3 更新子模块
git submodule update --remote这个命令会把子模块更新到远程仓库的最新提交。但注意，它不会自动修改主仓库里记录的子模块版本号。你需要手动提交这个变更。
我曾经在一个项目里，团队五个人，三个人的子模块版本不一致。原因是有人更新了子模块但忘了提交主仓库的指针变更。结果就是：你拉下来的代码，跟我拉下来的代码，行为不一样。排查了一下午才发现是子模块版本没对齐。
13.2 什么是 Git 子树？
子树的做法就粗暴多了——它直接把另一个仓库的代码合并到你的项目里，就像你手动复制粘贴一样。但 Git 会保留这个合并的历史记录，方便以后同步更新。
13.2.1 添加子树
git subtree add --prefix=themes/my-theme https://github.com/example/theme.git main --squash这里的 --squash 参数会把远程仓库的所有历史压缩成一次提交，避免你的项目历史被「污染」。我个人习惯加上这个参数，除非你有特殊需求。
13.2.2 拉取子树更新
git subtree pull --prefix=themes/my-theme https://github.com/example/theme.git main --squash13.2.3 推送回上游
git subtree push --prefix=themes/my-theme https://github.com/example/theme.git main这个功能是子模块没有的——你可以把子树里的修改推回给原始仓库。说白了，子树是双向的，子模块是单向的。
13.3 核心区别对比
| 对比维度 | git submodule | git subtree |
|---|---|---|
| 存储方式 | 引用指针，不存实际代码 | 实际代码合并到主仓库 |
| 克隆体验 | 需要额外 init + update | 直接克隆即可，代码就在里面 |
| 版本锁定 | 精确锁定提交哈希 | 通过 squash 提交锁定 |
| 修改后推送 | 需要分别推送子模块和主仓库 | 可以一次性推送，也可推回上游 |
| 历史复杂度 | 主仓库历史干净 | 合并后历史会变大 |
| 学习成本 | 中等，命令较多 | 较低，操作直观 |
13.4 知识体系结构图
下面这张图帮你理清两个工具的核心逻辑：
13.5 实际场景怎么选？
我根据自己的项目经验，给你几个判断标准：
13.5.1 用 submodule 的场景
- 外部依赖：比如第三方库、框架、主题，你只读不改
- 需要精确锁定版本：每个团队成员必须用完全一样的版本
- 不想让主仓库历史膨胀：子模块的提交历史不会混进主仓库
13.5.2 用 subtree 的场景
- 内部共享代码：比如公司内部的工具库，你可能会修改它
- 简化团队协作：不想教团队成员记一堆 submodule 命令
- 需要双向同步：你改了子树里的代码，还想推回原始仓库
如果是开源项目的依赖，我倾向于用 submodule。因为我不需要修改它，只需要锁定版本。但如果是公司内部的公共组件库，我会用 subtree。因为团队成员经常需要修改组件代码，subtree 的操作更直观，不容易出错。
13.6 避坑指南
最后分享几个我踩过的坑：
- 子模块分支切换问题：子模块默认处于 detached HEAD 状态。如果你在子模块里做了修改，记得先切回分支再提交。我曾经因为这个丢过修改，血的教训。
- 子树合并冲突：子树合并时如果产生冲突，解决起来比普通合并要麻烦一些。建议在子树更新前，先确保本地没有未提交的修改。
- 不要嵌套太深：子模块里再套子模块，维护成本会指数级上升。我见过一个项目嵌套了三层子模块，最后没人搞得清楚依赖关系。
好了，子模块和子树的核心内容就这些。你想想看，其实选哪个并不复杂——关键看你是「引用」还是「合并」。搞清楚了这一点，就不会选错了。