在 Git 中添加子模块（submodule）的详细步骤

在 Git 中添加子模块（submodule）的详细步骤如下：

---

1. 添加子模块

命令格式：

git submodule add <仓库URL> [目标路径]

• 仓库URL：子模块的 Git 仓库地址（HTTP/SSH 均可）。
• 目标路径（可选）：子模块在主仓库中的存放路径。若省略，默认使用仓库名称作为路径。

示例：

git submodule add https://github.com/example/thirdparty.git libs/thirdparty

• 将 thirdparty 仓库添加到主仓库的 libs/thirdparty 目录下。

执行后效果：

1. 克隆子模块仓库到指定路径。
2. 在主仓库根目录生成 .gitmodules 文件，记录子模块信息（URL 和路径）。
3. 在 .git/modules/ 目录下保存子模块的 Git 元数据。

---

2. 提交主仓库的变更

子模块添加后，主仓库会生成两个变更：

• .gitmodules 文件（新增）。
• 子模块路径对应的提交 ID（类似 160000 模式的文件）。

提交命令：

git commit -m "添加子模块: thirdparty"

---

3. 克隆含子模块的主仓库

其他协作者克隆主仓库后，需初始化子模块：

方式一：递归克隆（推荐）

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

• 一次性克隆主仓库并初始化所有子模块。

方式二：分步初始化

1. 克隆主仓库：

   git clone <主仓库URL>
   

2. 初始化子模块：

   git submodule init
   

3. 拉取子模块代码：

   git submodule update
   

---

4. 更新子模块

拉取子模块的最新代码

1. 进入子模块目录：

   cd libs/thirdparty
   

2. 拉取更新并切换至最新提交：

   git checkout main  # 切换到目标分支
   git pull
   

3. 返回主仓库目录，提交子模块的变更：

   cd ../..
   git add libs/thirdparty
   git commit -m "更新子模块 thirdparty 到最新版本"
   

批量更新所有子模块

git submodule foreach git pull

---

5. 删除子模块

1. 删除子模块条目：

   git rm -f libs/thirdpackage
   

2. 删除 .git/modules/thirdparty 目录（手动操作）：

   rm -rf .git/modules/libs/thirdpackage
   

3. 提交变更：

   git commit -m "移除子模块 thirdpackage"
   

---

注意事项

1. 路径冲突：确保目标路径为空，否则会报错 '<路径>' already exists。
2. 子模块独立性：子模块的修改需在子模块目录内单独提交，主仓库仅记录其提交 ID。
3. 分支跟踪：默认子模块处于“游离 HEAD”状态，如需跟踪分支，需手动切换：

   cd libs/thirdparty
   git checkout main
   

---

通过以上步骤，你可以将外部仓库作为子模块嵌入主项目，并管理其版本和更新。