Git进阶：如何将目录提取为新仓库？

在软件开发中，随着项目规模的扩大，某些模块可能需要独立为新的仓库。例如，一个公共组件库或工具目录可能需要独立维护。然而，传统的文件复制方式会丢失历史提交记录，导致代码审计和协作困难。本文将深入探讨如何从Git仓库中提取子目录并保留完整历史记录，同时提供多种方法的对比与实践建议。

---

一、核心方法对比

1. git subtree split方法（推荐保留历史）

适用场景 ：需要保留与子目录相关的所有提交记录，且目录结构简单。
步骤：

1. 克隆原仓库并进入目录：

   git clone <原仓库URL> && cd <原仓库目录>  

2. 提取子目录历史到新分支：

   git subtree split -P <子目录路径> -b <新分支名>  

   例如提取 src/components/button：

   git subtree split -P src/components/button -b new-button  

3. 初始化新仓库并拉取历史：

   mkdir ../new-repo && cd ../new-repo  
   git init  
   git pull ../原仓库目录 new-button  

4. 推送到远程仓库：

   git remote add origin <新仓库URL>  
   git push -u origin master  

优点 ：操作简单，历史记录完整。
缺点：若子目录路径多次变更，可能遗漏部分提交。

---

2. git filter-repo方法（现代高效）

适用场景 ：复杂历史清理、多目录过滤或路径重命名的情况。
步骤：

1. 安装工具（需Python环境）：

   pip install git-filter-repo  

2. 克隆原仓库并过滤子目录：

   git clone <原仓库URL> new-repo  
   cd new-repo  
   git filter-repo --path <子目录路径>  

3. 关联远程仓库并推送：

   git remote add origin <新仓库URL>  
   git push -u origin master  

优点 ：处理速度快，支持复杂过滤规则。
缺点：需额外安装工具，对旧版Git兼容性较差。

---

3. git filter-branch方法（传统方案）

适用场景 ：无git filter-repo权限或需要兼容旧版本Git。
步骤：

1. 克隆原仓库并删除旧远程：

   git clone <原仓库URL> new-repo  
   cd new-repo  
   git remote rm origin  

2. 过滤历史记录：

   git filter-branch --tag-name-filter cat --prune-empty \  
   --subdirectory-filter <子目录路径> -- --all  

3. 清理无效对象并推送：

   git reset --hard  
   git reflog expire --expire=now --all  
   git gc --aggressive --prune=now  
   git remote add origin <新仓库URL>  
   git push -u origin master  

优点 ：无需额外工具。
缺点：操作复杂，可能残留冗余对象。

---

二、进阶技巧与注意事项

1. 处理多分支场景

若需保留多个分支的历史，可对每个分支重复执行git subtree split或git filter-repo操作，再合并到新仓库的不同分支中。

2. 子模块与依赖管理

若原仓库包含子模块，需单独迁移：

1. 提取子模块路径：

   git submodule deinit <子模块路径>  
   mv <子模块路径> ../new-submodule  

2. 初始化新仓库并关联子模块。

3. 清理冗余数据

使用git gc和git prune优化新仓库体积，尤其在filter-branch后。

4. 协作通知与权限

迁移后需更新协作者权限，并在原仓库中标记子目录已弃用，避免后续冲突。

---

三、方法对比总结

方法	保留历史	操作复杂度	适用场景
git subtree split	是	中等	简单目录结构
git filter-repo	是	低	复杂过滤需求
git filter-branch	是	高	兼容旧版本Git