如何在主仓库中嵌入新Git仓库？多种尝试均遇阻

要在包含多个子仓库的主仓库中嵌入独立仓库，Git官方的标准方案是使用子模块（submodule），以下是完整的正确操作流程，以及你之前操作踩坑的排查：

一、完整新增子模块步骤 #

1. 进入主仓库根目录，确保工作区干净
   先执行git status检查，确保主仓库没有未提交的修改，避免冲突。

2. 添加子模块到主仓库
   执行以下命令，将目标仓库作为子模块嵌入指定路径：

   git submodule add <目标仓库Git地址> <本地存放路径>
   

   示例：如果目标仓库地址是git@github.com:example/target-repo.git，要放在主仓库的./modules/target目录，命令为：

   git submodule add git@github.com:example/target-repo.git ./modules/target
   

   执行后，主仓库会生成两个关键文件：

   • .gitmodules：记录所有子模块的配置信息
   • 子模块路径的占位条目：Git会将子模块作为特殊文件追踪

3. 拉取子模块的实际文件
   添加子模块后，默认只会生成配置和占位符，需要执行以下命令拉取目标仓库的内容：

   git submodule update --init --recursive
   

   这个命令会初始化子模块，并递归拉取所有嵌套的子模块（如果目标仓库本身也有子模块）。

4. 提交主仓库的修改
   将生成的.gitmodules文件和子模块路径提交到主仓库：

   git add .gitmodules ./modules/target
   git commit -m "Add submodule: target-repo"
   git push
   

二、你之前操作的问题排查 #

• 用git remote add upstream + git pull的方式无效：这种方法只是在本地目录手动关联了远程仓库，但Git不会将其识别为主仓库的子模块，因此只会生成占位符，不会自动拉取内容，必须用submodule的官方命令管理。
• 之前尝试submodule未成功：大概率是遗漏了git submodule update --init --recursive步骤，或者没有提交.gitmodules文件，导致子模块配置未被主仓库追踪。

三、后续克隆主仓库的注意事项 #

如果其他人克隆这个主仓库，需要带--recursive参数一次性拉取所有子模块：

git clone --recursive <主仓库Git地址>

如果已经克隆了主仓库但未获取子模块内容，执行：

git submodule update --init --recursive

内容的提问来源于stack exchange，提问作者Isabel Roman