如何将Git仓库目录替换为现有Git仓库并作为子模块保留历史？

假设你的主仓库为repo-main，要替换的目录是dir-to-replace；子仓库为repo-sub，远程地址是<sub-repo-url>。以下是具体操作步骤：

1. 处理主仓库，移除目标目录 #

• 克隆主仓库到本地（若已在本地可跳过此步）：

  git clone <main-repo-url> repo-main
  cd repo-main
  

• 删除要替换的目录及所有内容：

  git rm -r dir-to-replace
  

• 提交删除操作，记录这次变更：

  git commit -m "Remove dir-to-replace to make way for submodule"
  

2. 添加子模块到原目录位置 #

• 将子仓库作为子模块添加到主仓库的原目录路径下：

  git submodule add <sub-repo-url> dir-to-replace
  

• 提交子模块的添加操作：

  git commit -m "Add repo-sub as submodule at dir-to-replace"
  

• 推送主仓库的修改到远程：

  git push origin main
  

3. 验证子模块功能 #

• 新克隆主仓库时，需加上--recurse-submodules参数才能同步拉取子模块内容：

  git clone <main-repo-url> --recurse-submodules
  

• 若已克隆主仓库，可手动初始化并更新子模块：

  git submodule init
  git submodule update
  

关键说明 #

• 主仓库会保留自身所有提交历史（包括删除目录的那次提交），子模块作为独立仓库，完全保留自己的提交历史。
• 后续对子模块的修改，需进入子模块目录单独执行git commit、git push等操作，主仓库仅跟踪子模块的特定提交版本。

可选：彻底移除主仓库历史中的目标目录（谨慎操作） #

如果需要清理主仓库历史中dir-to-replace的所有痕迹（减小仓库体积），可使用git filter-repo工具重写历史：

• 安装git filter-repo工具（部分Git版本已内置）
• 在主仓库执行：

  git filter-repo --path dir-to-replace --invert-paths
  

• 强制推送到远程（注意：此操作会重写主仓库历史，所有协作成员需重新克隆或同步）：

  git push origin main --force
  

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