介绍 filter-repo-rs：一个高效重写 Git 仓库历史的 Rust 工具

TL;DR

filter-repo-rs 是一个用 Rust 编写的高性能 Git 仓库历史重写工具，灵感来源于 git-filter-repo。它通过流式处理 git fast-export 和 git fast-import，实现了对仓库历史的高效操作，例如清理敏感数据、重构目录、移除大文件等。本文将详细介绍其功能和使用场景。

正文#

什么是 `filter-repo-rs`？#

filter-repo-rs 是一个基于 Rust 实现的命令行工具，旨在提供一个比 git-filter-repo 更高效、更安全的替代方案，用于重写 Git 仓库的历史。它利用 git fast-export 导出仓库数据，通过一系列可配置的过滤器进行处理，最后通过 git fast-import 将修改后的历史写回仓库。

这个工具的核心优势在于其高性能的流式处理架构，这使得它在处理大型仓库时依然能保持出色的性能和较低的内存占用。

主要特性#

filter-repo-rs 提供了丰富的功能来满足各种历史重写需求：

🚀 高性能流式处理：基于 git fast-export → 过滤器 → git fast-import 的管道架构，处理速度快，内存占用低。
🔒 敏感数据清理：可以从提交历史中安全地移除 API 密钥、密码等敏感信息，无论是文件内容还是提交信息。
📁 灵活的路径操作：支持目录重构、文件删除、批量重命名等操作，方便调整项目结构。
🏷️ 引用管理：智能处理分支和标签的重命名与迁移。
💾 安全备份机制：在执行重写操作前，会自动备份原始历史，确保数据安全，支持完整恢复。
🔍 仓库分析工具：可以检查仓库的健康度，识别出大文件和潜在的问题。

核心用途和示例#

下面我们来看几个 filter-repo-rs 的典型使用场景。

1. 清理历史记录中的敏感数据#

当你不小心将密钥或令牌（如 API_TOKEN）提交到仓库时，需要从所有历史记录中彻底清除它。

首先，创建一个规则文件 redact.txt，定义要替换的内容，支持字面值和正则表达式：

SECRET_TOKEN==>REDACTED
regex:(API|TOKEN|SECRET)[A-Za-z0-9_-]+==>REDACTED

然后，执行以下命令来清洗所有引用（包括远程引用）中的敏感数据：

filter-repo-rs \
  --sensitive \
  --replace-text redact.txt \
  --write-report

操作完成后，你需要强制推送到远程仓库以覆盖旧的历史：

git push --force --all
git push --force --tags

2. 仓库瘦身：移除大文件#

如果你的仓库因为包含大文件而变得臃肿，可以使用 filter-repo-rs 来进行瘦身。

首先，分析仓库，找出体积较大的对象：

filter-repo-rs --analyze

你可以根据分析结果，按大小阈值移除超过 5MB 的文件：

filter-repo-rs --max-blob-size 5M --write-report

3. 调整仓库目录结构#

filter-repo-rs 也支持对目录结构进行调整。

例如，将 frontend 子目录提升为新的根目录：

filter-repo-rs --subdirectory-filter frontend

或者，将所有文件移动到一个新的 app/ 子目录中：

filter-repo-rs --to-subdirectory-filter app/

4. 批量重命名分支和标签#

你可以轻松地对分支和标签进行批量重命名。

例如，将所有以 v1. 开头的标签重命名为以 legacy/v1. 开头：

filter-repo-rs --tag-rename v1.:legacy/v1.

将所有以 feature/ 开头的分支重命名为以 exp/ 开头：

filter-repo-rs --branch-rename feature/:exp/

快速开始#

环境要求#

Git
Rust 工具链

构建和安装#

你可以通过 cargo 来构建和安装 filter-repo-rs：

cargo build -p filter-repo-rs --release

构建完成后，可执行文件位于 target/release/filter-repo-rs。

总结#

filter-repo-rs 是一个强大而高效的 Git 历史重写工具。凭借其高性能的 Rust 实现和丰富的功能集，它为开发者提供了一个安全、可靠的方式来管理和维护 Git 仓库。无论是清理敏感数据、重构项目结构，还是为仓库瘦身，filter-repo-rs 都表现出色。

虽然项目目前仍处于原型阶段，但其核心功能已经相当稳定。如果你正在寻找一个 git-filter-repo 的现代化替代品，filter-repo-rs 绝对值得一试。

更多信息，请访问项目主页：https://github.com/Cactusinhand/filter-repo-rs