什么是 Git submodules，有哪些替代方案？

Question

Accepted Answer

**Git submodules** 允许你在一个 Git 仓库内将另一个 Git 仓库作为子目录嵌入——用于将共享库或依赖项作为单独的仓库包含进来很有用。它们功能强大，但因复杂性而名声不佳，所以理解它们及其替代方案很有价值。 ## Submodules 是什么 ```text A SUBMODULE is a reference to ANOTHER Git repository at a SPECIFIC COMMIT, embedded in your repo as a subdirectory: → the parent repo records WHICH repo and WHICH commit (a pinned reference, not a copy) → the submodule is its own repo with its own history → Used to include shared libraries/components that are themselves versioned repos. ``` ```bash git submodule add path/to/lib # add a submodule git clone --recurse-submodules # clone a repo WITH its submodules git submodule update --init --recursive # initialize/fetch submodules after a normal clone git submodule update --remote # update submodules to their latest ``` ## 复杂性（为什么 submodules 比较复杂） ```text ⚠️ Submodules are pinned to a SPECIFIC COMMIT (not auto-updating) — easy to forget to update or commit the new reference ⚠️ Clones need --recurse-submodules (forgetting → empty submodule directories) ⚠️ Extra steps for updates; detached HEAD inside submodules; confusing for teams ⚠️ Changes in a submodule must be committed in the SUBMODULE repo, then the parent updated → multi-step, error-prone → Submodules work but have real ergonomic pain — a common source of team confusion. ``` ## 替代方案 ```text ✓ PACKAGE MANAGERS — publish the shared code as a package (npm, pip, Maven, etc.) and depend on a VERSION → usually the cleanest approach for shared libraries ✓ MONOREPO — keep everything in one repo (no submodules; tooling like Nx/Turborepo/Bazel) ✓ git subtree — merges another repo's content INTO yours (simpler than submodules in some ways; no extra clone steps, but its own trade-offs) → Often a package manager or monorepo is preferable to submodules. ``` ## 为什么这很重要理解 Git submodules 及其替代方案是**跨仓库管理共享代码和依赖** 的有价值的高级知识，因此对于代码组织的架构决策很有用。**Submodules** 解决了一个真实需求——将一个仓库嵌入另一个仓库中（作为对特定提交的固定引用），以包含作为版本化仓库的共享库或组件——理解它们如何工作（父级记录哪个仓库和提交，submodule 是它自己的仓库）和命令（添加、使用 `--recurse-submodules` 克隆、更新）在处理使用它们的项目时是必需的。 al关键是，理解**复杂性**很重要：submodules 有名副其实的复杂性——固定到特定提交（容易忘记更新）、克隆时需要 `--recurse-submodules`（忘记会留下空目录）、涉及多步骤容易出错的更新、让团队感到困惑——所以了解这些痛点可以设置现实期望并帮助避免常见的困扰。最有价值的是理解**替代方案**及其何时更可取：**包管理器**（将共享代码作为版本化包发布——通常是共享库的最清洁方法）、**monorepo**（将所有内容保留在一个仓库中并配备适当的工具）和 **git subtree**（合并另一个仓库的内容，有不同的权衡）。意识到包管理器或 monorepo 通常是比 submodules 更好的选择反映了良好的架构判断——认识到 submodules 虽然可用，但通常不是最佳解决方案。由于跨仓库管理共享代码是一个真实的架构问题，submodules（尽管复杂）是更好替代方案中的一个选项，理解 Git submodules、它们的复杂性以及替代方案（包管理器、monorepos、subtree）是做出关于代码共享和仓库组织的合理决策的有价值的高级知识，反映了选择正确方法而不是默认采用经常有问题的 submodules 的架构判断。