实战指南：如何将Git仓库中的特定文件夹及其历史完整迁移到另一个仓库

实战指南：如何将Git仓库中的特定文件夹及其历史完整迁移到另一个仓库

在软件项目的演进过程中，我们经常会遇到需要重构代码库的场景。一个常见的需求是：将一个庞大的单体仓库（Monorepo）中的某个模块或组件拆分出来，或者将一个项目中的公共部分提取到一个共享库中。这个过程中，最大的挑战莫过于如何在迁移文件的同时，完整地保留其宝贵的 Git 提交历史。

本文将通过一个真实场景，一步步教你如何使用 git filter-repo 和 git subtree 等强大工具，安全、高效地完成这一任务。

场景设定

假设我们有两个本地仓库：

1. 源仓库 (Source)：位于 E:\CODE\fork，这是一个功能复杂的项目。
2. 目标仓库 (Destination)：位于 E:\CODE\test，我们希望将源仓库的一部分功能迁移到这里。

我们的目标是：从源仓库中，只提取 axis 和 UserSrc 这两个文件夹，并将它们相关的、完整的 Git 历史记录，合并到目标仓库中。

第一步：筛选和剥离历史（使用 git filter-repo）

要从源仓库中精确地“剥离”出我们想要的文件夹历史，最好的工具是 git-filter-repo。它是一个现代、快速且安全的 Git 历史重写工具，是官方推荐用来替代老旧的 git filter-branch 的选择。

1. 准备工作：安全第一，操作于全新克隆

git-filter-repo 会进行破坏性的历史重写操作。为了防止对原始仓库造成任何意外的、不可逆的损害，必须在一个全新的克隆副本上执行所有操作。

首先，克隆一份源仓库的完整副本：

# 在一个合适的位置克隆源仓库
git clone E:\CODE\fork E:\CODE\fork-filtered# 进入这个新克隆的仓库
cd E:\CODE\fork-filtered

2. 执行筛选命令

现在，在这个全新的克隆仓库中，我们可以安全地执行筛选命令了。使用 --path 参数指定我们希望保留的文件夹。

git filter-repo --path axis/ --path UserSrc/

这条命令会遍历仓库的所有历史记录，并移除所有与 axis/ 和 UserSrc/ 无关的文件和提交。执行完毕后，这个 fork-filtered 仓库看起来就好像从诞生之初就只包含这两个文件夹。

3. 常见问题排查：Refusing to destructively overwrite...

在执行筛选时，你可能会遇到以下错误：

Aborting: Refusing to destructively overwrite repo history since
this does not look like a fresh clone.
...
Please operate on a fresh clone instead. If you want to proceed
anyway, use --force.

这是 git-filter-repo 的一个核心安全机制。它检测到你当前操作的仓库“不干净”（可能已经有过修改或不是刚克隆的状态），因此拒绝执行。

• 最佳解决方案：严格遵守规范，删除当前文件夹，然后重新执行第一步的 git clone 命令，确保操作在全新的克隆中进行。
• 备用方案（不推荐）：如果你非常确定当前仓库是个副本且可以被覆盖，可以使用 --force 标志强制执行：git filter-repo --path ... --force。

第二步：将筛选后的历史合并到目标仓库

现在，我们有了一个只包含目标文件夹和其历史的“干净”仓库。接下来，需要将它合并到我们的目标仓库 test_fixture_ME907 中。

这里介绍两种方法，其中 git subtree 因其优雅和结构清晰而备受推崇。

方法一：使用 git remote 和 pull (手动合并)

这个方法将筛选后的文件直接合并到目标仓库的根目录下。

1. 进入目标仓库：

   cd E:\CODE\test
   

2. 添加远程引用：将筛选后的仓库添加为一个临时的远程仓库。

   git remote add filtered_source E:\CODE\fork-filtered
   

3. 合并历史：因为两个仓库的历史源头不同，需要使用 --allow-unrelated-histories 选项来强制合并。

   # 假设筛选后仓库的主分支是 main
   git pull filtered_source main --allow-unrelated-histories
   

4. 清理：合并完成后，移除临时远程连接。

   git remote remove filtered_source
   

现在，axis 和 UserSrc 文件夹及其历史已经存在于目标仓库的根目录了。

方法二：使用 git subtree (推荐，更优雅)

git subtree 是为这种“将一个仓库作为子目录并入”的场景量身定做的。它能将所有引入的文件 neatly 存放在一个指定的子目录中，保持主项目结构的整洁。

1. 进入目标仓库：

   cd E:\CODE\test
   

2. 一键添加子树：

   # --prefix 定义了要存放这些文件的子目录名，可自定义
   # 后面跟上源仓库的路径和分支名
   git subtree add --prefix=test E:\CODE\fork-filtered main
   

这条命令会自动完成所有操作：添加远程、拉取、将文件放入 test 文件夹、合并历史并创建提交。整个过程一步到位，无需手动清理。

总结与最佳实践

通过本文的引导，我们成功地完成了从一个复杂 Git 仓库中剥离特定文件夹及其完整历史，并将其迁移到另一个仓库的全部流程。

回顾一下我们的最佳实践：

1. 选择正确的工具：使用 git filter-repo 进行历史筛选，它现代、高效且安全。
2. 安全第一：始终在全新的克隆仓库上执行破坏性操作，以保护原始数据。
3. 优雅地合并：当向现有项目添加代码时，优先使用 git subtree add --prefix=...，它可以将引入的代码整齐地组织在子目录中，使仓库结构更清晰，更易于维护。

掌握了这项技能，就能在未来的项目重构和代码库管理中游刃有余，自信地对 Git 仓库进行“外科手术”式的精准操作。