Git submodule 怎么管理项目中的外部依赖仓库？

Question

仓乃文 · Accepted Answer

项目需要引用另一个 Git 仓库的代码（如共享组件库、SDK），直接复制无法同步更新。submodule 将外部仓库作为子目录嵌入，保持独立版本控制，主仓库只记录子模块的提交引用。

添加子模块：
```bash
git submodule add https://github.com/org/shared-ui.git libs/shared-ui
# 会在项目中创建 libs/shared-ui 目录，指向指定仓库
git commit -m "chore: 添加 shared-ui 子模块"
```

克隆含子模块的项目：
```bash
# 方式一：递归克隆
git clone --recurse-submodules https://github.com/org/project.git

# 方式二：克隆后初始化
git clone https://github.com/org/project.git
cd project
git submodule update --init --recursive
```

更新子模块到最新：
```bash
cd libs/shared-ui
git pull origin main           # 在子模块目录拉取更新
cd ../..
git add libs/shared-ui         # 更新主仓库的子模块引用
git commit -m "chore: 更新 shared-ui 子模块"
```

补充说明：
- 子模块默认处于 detached HEAD 状态，修改前先 git checkout main
- .gitmodules 文件记录子模块的路径和远程地址
- git submodule foreach 可以在所有子模块中执行命令
- 子模块管理较复杂，替代方案有 Git Subtree 和 npm 包
- 团队克隆项目后必须执行 submodule update --init --recursive