将Git子文件夹迁移至新仓库并重新作为子模块添加的完整方案咨询

我刚好折腾过一模一样的需求，这套步骤能帮你完美实现——不仅把目标子文件夹剥离成拥有完整历史的独立仓库，还能在原仓库的所有历史节点中彻底移除该文件夹的痕迹，最后再以submodule的形式把新仓库加回原位置，完全保留原来的目录结构。

第一步：剥离子文件夹到新独立仓库 #

首先咱们得把目标文件夹从原仓库里分离出来，生成一个全新的仓库，同时保留它的所有提交历史：

1. 先克隆原仓库的镜像副本（别直接在原仓库操作，避免搞砸）：

   git clone --mirror https://github.com/your-username/original-repo.git
   cd original-repo.git
   

2. 使用git filter-repo（GitHub现在推荐这个工具，比filter-branch更稳定高效）来过滤出目标文件夹：

   git filter-repo --subdirectory-filter path/to/your/folder
   

   如果你坚持用filter-branch（就是你提到的GitHub文档里的命令），可以用这个，但注意它已经被官方标记为弃用：

   git filter-branch --prune-empty --subdirectory-filter path/to/your/folder master
   

3. 现在这个镜像仓库已经变成只包含目标文件夹内容的仓库了，咱们把它推送到新的远程仓库：

   git remote add new-origin https://github.com/your-username/new-submodule-repo.git
   git push new-origin --all
   git push new-origin --tags
   

4. 完成后退出这个镜像目录，咱们接下来处理原仓库。

第二步：清理原仓库的历史，彻底移除目标文件夹 #

现在要让原仓库的所有历史记录里都不再出现这个文件夹的痕迹：

1. 回到你的原仓库本地工作区（或者重新克隆一份干净的）：

   cd ../original-repo
   # 或者重新克隆：git clone https://github.com/your-username/original-repo.git
   

2. 同样用git filter-repo移除目标文件夹的所有历史：

   git filter-repo --invert-paths --path path/to/your/folder
   

   对应filter-branch的命令是：

   git filter-branch --prune-empty --index-filter "git rm -r --cached --ignore-unmatch path/to/your/folder" --tag-name-filter cat -- --all
   

3. 清理本地的冗余对象，确保历史完全干净：

   git for-each-ref --format="delete %(refname)" refs/original | git update-ref --stdin
   git reflog expire --expire=now --all
   git gc --prune=now
   

4. 强制推送到原仓库（重要提醒：这会改写原仓库的历史，一定要提前通知所有协作的开发者，让他们重新克隆仓库或者用git rebase处理本地分支）：

   git push origin --force --all
   git push origin --force --tags
   

第三步：将新仓库作为Submodule添加回原仓库的原位置 #

最后一步就是把刚创建的独立仓库以submodule的形式加回原仓库的对应目录，保持原来的结构：

1. 在原仓库的根目录执行submodule添加命令，指定目标路径为原来的文件夹路径：

   git submodule add https://github.com/your-username/new-submodule-repo.git path/to/your/folder
   

2. 初始化并更新submodule：

   git submodule init
   git submodule update
   

3. 提交这个变更到原仓库：

   git add .gitmodules path/to/your/folder
   git commit -m "Replace folder with submodule"
   git push origin master
   

关键注意事项 #

• 备份优先：在执行所有改写历史的操作前，一定要备份原仓库和新仓库的镜像，避免数据丢失。
• 协作沟通：改写原仓库历史后，所有协作开发者必须丢弃本地旧分支，重新克隆或者执行git fetch origin后git rebase origin/master（如果他们有未提交的更改）。
• 子模块维护：后续原仓库的提交不会自动同步子模块的更改，需要在子模块目录里单独提交推送，然后在原仓库里提交子模块的更新。

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