Git Filter-Repo 实用技巧：解决 Git 历史疑难杂症 – wiki基地

作者： /

Git Filter-Repo 实用技巧：解决 Git 历史疑难杂症

Git 是现代软件开发中不可或缺的版本控制系统。然而，随着项目的迭代和演进，Git 历史记录有时会变得混乱，甚至包含敏感信息或不必要的大文件。此时，我们需要一种强大的工具来重写、清理和优化 Git 历史。git filter-repo 正是为此而生，它以其卓越的性能和灵活性，成为了处理 Git 历史疑难杂症的首选方案。

一、为何选择 Git Filter-Repo？

在 git filter-repo 出现之前，git filter-branch 是主要的 Git 历史重写工具。然而，filter-branch 存在一些显著的缺点：

  1. 性能低下：对于大型仓库，filter-branch 的运行速度极慢，因为它需要逐一检查每个 commit。
  2. 复杂难用：其脚本接口相对复杂，容易出错，并且难以进行高级过滤操作。
  3. 安全性问题：在某些情况下，它可能无法彻底清除历史中的所有敏感信息。

git filter-repo 旨在解决这些痛点。它由 Git 官方维护，使用 Python 编写，具备以下优势：

  • 极速性能：通过更优化的算法和并行处理，filter-repo 的运行速度远超 filter-branch，尤其是在大型仓库上。
  • 简单直观：提供清晰简洁的命令行接口，通过各种选项即可实现复杂的历史重写操作。
  • 功能强大：支持删除文件、修改 commit 信息、更改作者信息、拆分合并仓库等多种场景。
  • 安全性高：能够更彻底地移除不再需要的数据，确保敏感信息不会残留在历史中。

二、安装 Git Filter-Repo

git filter-repo 是一个独立的 Python 脚本，可以通过 pip 轻松安装：

bash
pip install git-filter-repo

安装完成后，确保 git-filter-repo 命令可以在你的 PATH 环境变量中找到。

三、使用前的警告与准备

历史重写是破坏性操作！ 它会改变所有相关 commit 的 SHA-1 校验和。这意味着：

  1. 务必备份！ 在执行任何 git filter-repo 操作前，请务必完整备份你的 Git 仓库。
  2. 通知协作者！ 如果你在一个团队中工作，并且重写了共享历史，所有协作者都需要删除本地仓库，然后重新克隆，或者进行复杂的 git rebase --hard 操作，并删除本地的所有远程分支。
  3. 强制推送：重写历史后，你需要使用 git push --force-with-lease 或 git push --force 命令来更新远程仓库。--force-with-lease 更安全，因为它会检查远程分支是否在上次拉取后被他人更新。

四、Git Filter-Repo 实用技巧与示例

以下是一些 git filter-repo 的常见使用场景和技巧。在执行这些命令之前，请确保你已经切换到要操作的 Git 仓库根目录。

1. 彻底移除敏感文件或大文件

这是 filter-repo 最常见的用途之一。假设你不小心将一个包含密码的文件或一个巨大的二进制文件提交到了仓库历史中。

场景 1：删除单个文件

bash
git filter-repo --path sensitive_data.txt --invert-paths --force

  • --path sensitive_data.txt：指定要操作的路径。
  • --invert-paths：表示“除了这个路径之外的所有路径都保留”，也就是删除这个路径。
  • --force：强制执行，因为这会改变历史。

场景 2：删除特定类型的所有文件

bash
git filter-repo --path-glob '*.log' --invert-paths --force

  • --path-glob '*.log'：使用 glob 模式匹配所有 .log 文件。

场景 3：删除特定目录

bash
git filter-repo --path my_large_assets/ --invert-paths --force

  • 注意目录末尾的斜杠 /，这确保只匹配目录。

场景 4：删除符合多个条件的文件

如果你需要删除多个文件或模式，可以重复使用 --path 或 --path-glob：

bash
git filter-repo --path sensitive_data.txt --path-glob '*.DS_Store' --invert-paths --force

2. 批量修改 Commit 信息

当你的 commit 信息不规范，或者需要统一格式时，此功能非常有用。

bash
git filter-repo --message-callback 'return message.replace(b"fixbug:", b"Fix:")' --force

  • --message-callback：接受一个 Python 表达式或文件，用于处理 commit 信息。
    • message 是一个 bytes 对象，表示原始 commit 信息。
    • 你需要返回一个新的 bytes 对象。
  • 上述例子将所有 “fixbug:” 替换为 “Fix:”。

3. 更改作者/提交者信息

有时你需要统一 Git 历史中的作者信息（例如，因为使用了错误的邮箱或名称）。

bash
git filter-repo --mailmap --force

此命令会查找仓库根目录下的 .mailmap 文件。.mailmap 文件的格式如下：

Correct Name <[email protected]> <[email protected]>
Correct Name <[email protected]> Old Name <[email protected]>

你也可以直接在命令行中指定：

bash
git filter-repo --commit-callback '
if commit.author_name == b"Old Name":
commit.author_name = b"New Name"
commit.author_email = b"[email protected]"
if commit.committer_name == b"Old Name":
commit.committer_name = b"New Name"
commit.committer_email = b"[email protected]"
' --force

  • --commit-callback：允许你编写 Python 代码来修改每个 commit 对象。
  • commit.author_name, commit.author_email, commit.committer_name, commit.committer_email 都是 bytes 对象。

4. 拆分一个大型仓库为多个小仓库

如果你的一个仓库包含了多个不相关的项目，并且你希望将它们拆分。

假设你的仓库结构如下：
my-mono-repo/
├── project_A/
├── project_B/
└── shared_stuff/

拆分出 project_A 为独立仓库：

“`bash

首先，在一个新的克隆副本上操作

git clone original_repo_url my_project_A_repo
cd my_project_A_repo

过滤并只保留 project_A 目录

git filter-repo –subdirectory-filter project_A/ –force
“`

执行后，my_project_A_repo 将只包含 project_A 目录下的文件，并且该目录将成为新仓库的根目录。

5. 合并多个小仓库为一个仓库

将多个独立的小仓库合并到一个新的大仓库中，并保留它们的历史。

假设你有 repo_A 和 repo_B 两个仓库，想合并到 mono_repo。

“`bash

1. 创建新的 monorepo

mkdir mono_repo
cd mono_repo
git init
git remote add origin

2. 从 repo_A 导入历史到 project_A 目录

git remote add repo_A
git pull repo_A master –allow-unrelated-histories
git filter-repo –to-subdirectory-filter project_A/ –force
git remote remove repo_A
git add .
git commit -m “Import project A”

3. 从 repo_B 导入历史到 project_B 目录

git remote add repo_B
git pull repo_B master –allow-unrelated-histories
git filter-repo –to-subdirectory-filter project_B/ –force
git remote remove repo_B
git add .
git commit -m “Import project B”

4. 清理并推送到远程

git gc –prune=now
git push -u origin master
“`

  • --to-subdirectory-filter project_A/：将所有文件移动到 project_A/ 子目录下。

6. 只保留特定路径（例如，从一个大型仓库中提取子模块）

如果你只想从一个大型仓库中提取某个子路径，并丢弃其他所有历史。

“`bash

在一个临时的克隆副本上操作

git clone original_repo_url temp_repo
cd temp_repo

git filter-repo –path some/specific/path/ –force
“`

执行后，temp_repo 将只包含 some/specific/path/ 目录下的文件，并且该目录将成为新仓库的根目录。

五、清理与优化

git filter-repo 运行后，你的本地仓库会包含大量不再被引用的旧对象。为了彻底清除它们并减小仓库体积，你需要执行垃圾回收：

“`bash

删除所有被 filter-repo 替换的旧引用

git for-each-ref –format=”delete %(refname)” refs/original | git update-ref –stdin

清理不再需要的对象

git reflog expire –expire=now –all
git gc –prune=now
“`

这些命令将确保旧的、被重写历史抛弃的对象被彻底清除。

六、总结

git filter-repo 是一个极其强大和高效的 Git 历史重写工具，能够解决 Git 仓库中遇到的各种复杂问题，如移除敏感数据、清理大型文件、修改提交者信息、拆分或合并仓库等。然而，其强大功能也伴随着风险，在任何操作之前务必进行备份，并确保团队成员知晓并配合更新其本地仓库。 掌握 git filter-repo，你将能够更好地管理和优化你的 Git 历史，使项目更加整洁、高效和安全。

滚动至顶部