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

文章目录

- 实战指南：如何将Git仓库中的特定文件夹及其历史完整迁移到另一个仓库
- - 场景设定
  - [第一步：筛选和剥离历史（使用 `git filter-repo`）](#第一步：筛选和剥离历史（使用 git filter-repo）)
  - - [1. 准备工作：安全第一，操作于全新克隆](#1. 准备工作：安全第一，操作于全新克隆)
    - [2. 执行筛选命令](#2. 执行筛选命令)
    - [3. 常见问题排查：`Refusing to destructively overwrite...`](#3. 常见问题排查：Refusing to destructively overwrite...)
  - 第二步：将筛选后的历史合并到目标仓库
  - - [方法一：使用 `git remote` 和 `pull` (手动合并)](#方法一：使用 git remote 和 pull (手动合并))
    - [方法二：使用 `git subtree` (推荐，更优雅)](#方法二：使用 git subtree (推荐，更优雅))
  - 总结与最佳实践

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

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

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

场景设定

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

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

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

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

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

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

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

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

bash 复制代码

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

# 进入这个新克隆的仓库
cd E:\CODE\fork-filtered

2. 执行筛选命令

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

bash 复制代码

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

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

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

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

log 复制代码

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` (手动合并)

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

进入目标仓库：
bash 复制代码
```
cd E:\CODE\test
```
添加远程引用：将筛选后的仓库添加为一个临时的远程仓库。
bash 复制代码
```
git remote add filtered_source E:\CODE\fork-filtered
```
合并历史 ：因为两个仓库的历史源头不同，需要使用 --allow-unrelated-histories 选项来强制合并。
bash 复制代码
```
# 假设筛选后仓库的主分支是 main
git pull filtered_source main --allow-unrelated-histories
```
清理：合并完成后，移除临时远程连接。
bash 复制代码
```
git remote remove filtered_source
```

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

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

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

进入目标仓库：
bash 复制代码
```
cd E:\CODE\test
```

一键添加子树：

bash 复制代码

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

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

总结与最佳实践

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

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

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

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

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

文章目录