要在一个 GitHub 仓库中引用多个子仓库，你需要使用 **Git Submodule（Git 子模块）** 功能。子模块允许你将一个 Git 仓库作为另一个 Git 仓库的子目录。主仓库（父仓库）只会记录子模块仓库的**特定提交（Commit）**，而不是子仓库的全部内容。这非常适合管理依赖项、库，或者将大型项目拆分成独立的代码库。以下是实现这一目标的操作步骤： ----- ## 1\. 添加子模块（引用子仓库）在你的主仓库（父仓库）的根目录下执行以下命令，为每一个需要引用的子仓库重复此操作。 ### 基本命令 ```bash git submodule add <子仓库的URL> <希望在父仓库中显示的路径> ``` - **`<子仓库的URL>`**: 子仓库（GitHub 仓库）的 URL，可以是 HTTPS 或 SSH 格式。 - **`<希望在父仓库中显示的路径>`**: 你希望将子仓库克隆到的本地目录路径（相对于父仓库根目录）。如果不指定，默认使用仓库名称。 ### 示例假设你要添加两个子仓库 `LibA` 和 `UtilsB`： ```bash # 添加第一个子仓库 LibA git submodule add https://github.com/your-org/LibA.git lib/lib-a # 添加第二个子仓库 UtilsB git submodule add https://github.com/your-org/UtilsB.git utils/b ``` ### 做了什么？执行 `git submodule add` 后，会发生以下变化： 1. **克隆子仓库**: 子仓库会被克隆到你指定的路径下（例如 `lib/lib-a`）。 2. **创建 `.gitmodules` 文件**: Git 会在主仓库的根目录创建一个名为 `.gitmodules` 的配置文件，其中记录了子仓库的 URL 和路径信息。这个文件需要被版本控制。 3. **记录子仓库的特定提交**: 主仓库的索引会记录子仓库当前所在分支的 **最新提交的 SHA-1 值**。 ----- ## 2\. 提交子模块的更改添加完所有子模块后，你需要将这些变动提交到你的主仓库。 ```bash # 查看状态，你会看到 .gitmodules 文件和子模块目录的变动 git status # 添加并提交变动 git commit -m "Add LibA and UtilsB submodules" # 推送到 GitHub git push origin <你的分支名> ``` 现在，你的主仓库就成功引用了多个子仓库。其他用户克隆你的主仓库时，就可以看到子模块信息了。 ----- ## 3\. 克隆包含子模块的仓库（给其他用户）当其他人克隆你这个包含子模块的主仓库时，他们不能只用 `git clone`。默认情况下，**子模块的内容不会被自动下载**。他们需要执行以下两种操作之一： ### 选项 A: 首次克隆时就下载所有子模块这是最推荐的方式。 ```bash git clone --recursive <你的主仓库URL> ``` ### 选项 B: 先克隆主仓库，再初始化和更新子模块如果他们已经克隆了主仓库，但子模块目录是空的，则需要执行以下两条命令： ```bash # 1. 初始化本地配置文件 git submodule init # 2. 拉取子模块内容并检出主仓库记录的特定提交 git submodule update # 或者使用 -j 并行下载多个子模块，提高速度 # git submodule update --init --recursive -j 8 ``` ----- ## 核心概念总结 1. **主仓库只记录 SHA-1**：主仓库只关心它引用的子仓库的**哪个特定提交**。如果你更新了子仓库，父仓库并不会自动感知，需要你在父仓库中明确提交这个“引用的更新”。 2. **`.gitmodules`**：这是一个配置文件，位于主仓库根目录，它记录了所有子模块的名称、路径和 URL。 3. **子模块是独立的仓库**：你可以进入任何子模块目录，像操作一个独立的 Git 仓库一样进行 `git pull`、`git commit`、`git push` 等操作。 ## 删除子模块删除 Git 子模块（Submodule）需要执行几个步骤，因为子模块的引用信息分散在不同的位置。仅仅删除目录是不够的。请确保你现在处于\*\*主仓库（父仓库）\*\*的根目录下。以下是完整的删除步骤： ### 步骤 1: 移除子模块记录使用 `git submodule deinit` 命令来清除子模块在本地 `.git/config` 文件中的配置信息，然后使用 `git rm` 命令从版本控制中删除子模块目录。 ```bash # 1. 停止追踪并移除本地配置（用你实际的子模块路径替换） git submodule deinit # 2. 从主仓库的工作区和索引中删除子模块目录（不带末尾的斜杠 /） # --cached 参数很重要，它只删除索引中的记录，但保留本地文件，以便后续删除 git rm --cached ``` **例如，如果你要删除名为 `lib/lib-a` 的子模块：** ```bash git submodule deinit lib/lib-a git rm --cached lib/lib-a ``` ### 步骤 2: 手动清除残留文件 `git rm --cached` 命令只是删除了 Git 索引中的引用，但子模块的实际目录可能仍然存在。你需要手动删除它。 ```bash # 3. 手动删除子模块的工作目录 rm -rf # 4. （可选）删除主仓库中残留的 .git 目录条目 # 这一步是为了彻底清除 Git 对该子模块的引用，确保干净。 # 使用你实际的子模块名称替换。子模块名称通常是路径的最后一部分，如 lib-a rm -rf .git/modules/ ``` ### 步骤 3: 提交并推送更改你需要将 `.gitmodules` 文件和子模块删除操作提交到主仓库。 ```bash # 5. 查看状态：你会看到 .gitmodules 文件被修改，子模块目录被删除 git status # 6. 提交更改 git commit -m "Remove submodule " # 7. 推送到远程仓库 git push origin <你的分支名> ``` 完成这些步骤后，该子模块就从你的主仓库中彻底移除了。 ----- ### 💡 针对旧版 Git 的说明如果你的 Git 版本比较老（低于 2.x），你可能需要手动编辑 `.gitmodules` 和 `.git/config` 文件： 1. **手动编辑 `.gitmodules` 文件**：删除与该子模块相关的所有行。 2. **手动编辑 `.git/config` 文件**：删除 `[submodule "submodule_name"]` 整个配置块。 3. 然后执行： ```bash git rm --cached rm -rf # rm -rf .git/modules/ git commit -m "Remove submodule " ``` **不过，推荐使用上述的 `git submodule deinit` 命令，因为它会自动清理本地配置，更加方便和安全。**