007-git子模块管理

子模块有自己的第三方依赖，应该如何一步到位?

针对“子模块有自己的第三方依赖”这个场景，实现“一步到位”拉取所有依赖的核心，就是使用 Git 的递归（--recursive） 选项。

根据你当前所处的状态，可以选择以下对应的“一步到位”命令：

场景一：首次克隆项目（一步到位）

如果你还没克隆主项目，这是最简单的情况。直接在 git clone 时加上 --recurse-submodules 参数即可。

git clone --recurse-submodules <你的仓库URL>

这个命令会克隆主项目，并自动初始化、拉取所有层级的子模块，让项目立即可用。

提速小技巧：如果子模块很多，可以加上 --jobs 参数来并行下载，例如 git clone --recurse-submodules --jobs 8。

场景二：已经克隆了主项目（补救措施）

如果你已经克隆了主项目，但子模块目录是空的，可以用下面这个命令一键补全所有依赖：

git submodule update --init --recursive

这个命令会初始化本地配置（--init），并递归地拉取所有嵌套的子模块（--recursive）。

场景三：更新已有的子模块依赖

当主项目更新，引入了新的子模块依赖，或者需要将现有子模块更新到父项目记录的最新提交时，可以使用：

git pull --recurse-submodules

这个命令在拉取主项目最新代码的同时，会自动更新所有子模块。

（可选）一劳永逸的配置

如果你觉得每次都要加 --recurse-submodules 太麻烦，可以设置一个全局选项，让 Git 在所有涉及子模块的操作中都默认启用递归：

git config --global submodule.recurse true

设置后，普通的 git pull 和 git submodule update 会自动带上递归行为。

总结：一张图看懂怎么选

你的现状	一步到位命令
还没克隆项目	`git clone --recurse-submodules <URL>`
已克隆，子模块为空	`git submodule update --init --recursive`
已克隆，需更新依赖	`git pull --recurse-submodules`
想以后都自动递归	`git config --global submodule.recurse true`

根据你的情况选择对应的命令，就能一次性拉取所有层级的子模块依赖了。

git submodule不再依赖，需要删除

在 Git 中删除一个不再依赖的子模块，官方推荐且最干净的命令是：

# 1. 反注册并清理子模块（取消注册 + 清空目录）
git submodule deinit -f <子模块路径>

# 2. 从 Git 仓库中彻底移除（删除索引和 .gitmodules 中的记录）
git rm -f <子模块路径>

# 3. 提交这次变更
git commit -m "移除不再依赖的子模块 <子模块路径>"

只需要这三步即可。执行完 git rm 后，git status 会显示修改了 .gitmodules 并删除了子模块目录，直接 commit 就行。

详细步骤拆解（含原理）

为了确保万无一失，你可以按下面的顺序操作：

1. 反注册（deinit） 这会清空子模块目录中的文件（避免残留），并删除 .git/config 中对该子模块的配置记录。

git submodule deinit -f path/to/submodule

（如果子模块有本地未提交的修改，必须加 -f 强制清理）

2. 移除索引（rm） 这会从 Git 的暂存区（Index）中移除该子模块，并自动帮你删除 .gitmodules 文件中对应的条目。

git rm -f path/to/submodule

注意：以前的旧教程会让你手动编辑 .gitmodules，现在不需要了，git rm 会自动处理。

3. 清理裸仓库缓存（强烈建议） 虽然 git rm 移除了引用，但子模块的历史对象（.git/modules/<路径>）还留存在本地。为了释放磁盘空间，可以手动删除：

rm -rf .git/modules/path/to/submodule

4. 提交

git commit -m "chore: remove submodule xxx"

验证是否删除干净

执行完上述步骤后，你可以检查以下三处，如果都没了，说明彻底干净了：

.gitmodules 文件中没有该子模块条目。
.git/config 文件中没有 [submodule "path"] 条目。
.git/modules/<路径> 文件夹不存在。

如果你已经错误地手动删除了目录…

如果你之前直接用 rm -rf 删了子模块文件夹，没有走 git submodule 命令，导致 git status 全是 modified: 和 untracked，那就需要先恢复，再按标准步骤来：

# 先恢复子模块（拉取回来）
git submodule update --init --recursive

# 然后再执行上面的标准三步删除法

按照这个流程操作，你的 git status 会非常干净，不会留下任何“脏”文件。如果你在执行过程中遇到 pathspec 报错，可以检查一下路径是否正确（路径是相对于项目根目录的，末尾不要带斜杠）。😊

git clone 一步到位

使用 git clone 获取带有子模块的项目，核心在于确保子模块的代码也被完整下载。主要有两种方法：

🚀 方法一：克隆时一步到位（最推荐）

在克隆主仓库时，直接使用 --recurse-submodules 参数，Git 会自动初始化并更新所有子模块。

git clone --recurse-submodules <主仓库URL>

补充说明：

--recursive 是旧版别名：在 Git 旧版本中，--recursive 与 --recurse-submodules 功能完全相同。建议直接使用 --recurse-submodules，含义更清晰。
并行下载加速：可添加 -j 参数指定并行下载的子模块数量，能显著提升克隆速度。
```
git clone --recurse-submodules -j8 <主仓库URL>
```

🛠️ 方法二：分步操作（适用于已克隆的仓库）

如果你已经克隆了主仓库，但忘记下载子模块，可以后续补上。

进入主仓库目录：
```
cd <主仓库目录>
```
初始化子模块配置：
```
git submodule init
```
拉取子模块数据并切换到正确的提交：
```
git submodule update
```

💡 高效组合命令

对于已克隆的仓库，可以直接使用组合命令，一步完成初始化和更新：

git submodule update --init --recursive

这里的 --recursive 用于处理子模块自身可能还包含子模块的情况。

⚙️ 其他实用场景

更新已有子模块：当主仓库更新后，可使用以下命令同步所有子模块：
```
git pull --recurse-submodules
```
克隆时拉取子模块最新提交：如果想在克隆时就让子模块跟踪其远程仓库的最新提交，而非主仓库记录的特定版本，可以使用 --remote-submodules 选项。
```
git clone --recurse-submodules --remote-submodules <主仓库URL>
```

💎 总结

最推荐：直接使用 git clone --recurse-submodules <主仓库URL>。
已克隆项目：在项目根目录执行 git submodule update --init --recursive。