如何将Git特性分支中的子目录逐步迁移为独立仓库并保留提交历史

你的场景优先选择 Git Subtree 方案，完全匹配「暂不改变现有路径、支持双仓库独立提交、后续平滑迁出不丢失历史」的需求，相比submodule对现有开发的侵入性更低，项目其他成员无感知，不需要额外学习子模块相关操作。

步骤1：从特性分支提取Module_A完整历史，生成独立仓库 #

所有操作先在Program仓库的本地副本上执行，不会改动原仓库的代码：

• 先切换到存放Module_A的特性分支：

  git checkout <你的特性分支名>
  

• 复制一份本地Program仓库到其他目录，专门用于提取子目录历史：

  # 替换为你本地Program仓库的路径
  git clone /path/to/local/Program ./Module_A_Standalone
  cd Module_A_Standalone
  

• 使用git filter-repo（Git官方推荐的历史编辑工具，替代旧的filter-branch）提取Package_C/Module_A路径下的所有提交：

  git filter-repo --subdirectory-filter Package_C/Module_A
  

• 给独立仓库绑定远程地址并推送，此时你已经得到了包含Module_A全量提交历史的独立仓库：

  git remote add origin <Module_A独立仓库的远程Git地址>
  git push -u origin main
  

步骤2：将独立仓库作为Subtree挂载回原路径，不改变现有依赖关系 #

回到原Program仓库的特性分支执行操作，全程不会改动Program/Package_C/Module_A的访问路径：

• 先删除原仓库中普通版本的Module_A目录并提交：

  git rm -r Package_C/Module_A
  git commit -m "chore: 移除原生Module_A目录，准备挂载为Subtree"
  

• 将Module_A独立仓库作为Subtree添加到原路径：

  git subtree add --prefix=Package_C/Module_A <Module_A独立仓库的远程Git地址> main --squash
  

  可选说明：--squash参数会将独立仓库的历史压缩为单个提交导入主仓库，避免主仓库历史冗余，若需要在主仓库保留Module_A的完整提交历史可删除该参数。

日常双仓库提交操作 #

配置完成后即可实现两端独立管理：

• 若在主仓库修改了Module_A的代码，需要同步到独立仓库：

  git subtree push --prefix=Package_C/Module_A <Module_A独立仓库的远程Git地址> main
  

• 若独立仓库有更新，需要同步到主仓库：

  git subtree pull --prefix=Package_C/Module_A <Module_A独立仓库的远程Git地址> main --squash
  

步骤3：插件系统落地后完全迁出Module_A #

不需要额外操作，直接在主仓库删除Subtree目录提交即可：

git rm -r Package_C/Module_A
git commit -m "feat: 插件系统上线，移除内置Module_A依赖"

此时Module_A独立仓库的全量开发历史会完整保留，不会有任何丢失。

为什么不选择Git Submodule？ #

Submodule挂载后目录下仅存储commit哈希引用，不会存放实际代码，其他项目成员拉取代码后需要额外执行submodule init、submodule update操作才能拿到Module_A的代码，对现有开发流程侵入性高，后续迁出时还需要额外清理.gitmodules配置，远不如Subtree适配渐进式迁移的场景。

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