Git仓库清理实战：使用git filter-repo优化大型项目仓库体积

随着时间的推移，Git仓库的体积会不断膨胀。例如，一个项目的仓库达到了2GB，导致新成员克隆需要近20分钟，在网络不佳时容易失败，严重影响开发体验。

问题根源：.git目录

查看项目目录，会发现实际工作文件体积并不大，膨胀主要来自于隐藏的.git目录。这个目录是Git版本控制的核心数据库，存储着所有的历史提交、分支信息和对象数据。

.git目录中占用空间最大的通常是objects子目录，它使用内容寻址方式存储所有文件（Blob）、目录结构（Tree）和提交（Commit）的历史版本。相比之下，config、logs等目录的占用可以忽略不计。

那么，具体是哪些历史文件导致了膨胀呢？

定位历史大文件

要快速、准确地分析Git仓库中历史文件的存储占用，可以使用git filter-repo工具的分析功能。在仓库根目录执行：

git filter-repo --analyze

命令执行后，会在.git/filter-repo/analysis目录下生成报告。重点关注path-all-sizes.txt文件，它列出了所有文件在整个历史记录中的总占用空间，从而帮助我们定位需要清理的“历史债务”。

常见的“历史债务”包括：误提交的构建产物目录（如/dist）、依赖包压缩文件（如node_modules.tgz）等。在决定移除前，必须确认这些文件已不再需要，因为此操作不可逆。

解决方案对比

确认文件可移除后，主要有两种方案。

方案一：建立新仓库（治标快，但丢历史）

此方案最为直接高效：基于当前最新代码创建一个全新的仓库，彻底抛弃旧有的提交历史。
操作步骤：

1. 通知所有开发者暂停向旧仓库提交代码。
2. 创建新的远程仓库并配置权限。
3. 新建目录，初始化Git并关联新远程仓库。
4. 将旧仓库最新版的工作文件（排除.git目录）复制到新目录。
5. 提交并推送到新远程仓库。
6. 通知团队切换至新仓库，旧仓库仅用于历史查询。

优点：操作简单，瞬间解决体积问题。
缺点：完全丢失项目历史记录，只能回旧仓库查询。

方案二：使用工具清理历史（保留历史，但操作复杂）

这是Git官方推荐的深度清理方案，使用git filter-repo工具重写历史，永久删除指定的大文件。这属于高级的运维/DevOps操作，耗时较长，需谨慎执行。

前提：操作期间必须确保无人向仓库推送代码，否则可能前功尽弃。建议临时移除其他开发者的推送权限。

操作流程：

1. 做好备份：完整克隆或Fork原仓库。
2. 执行逻辑删除：使用git filter-repo命令从历史中移除目标文件。

   git filter-repo \
     --path deploy_temp/dist.zip \
     --path node_modules.tgz \
     --invert-paths \
     --force

   （--invert-paths表示保留不包含这些路径的历史，--force确保强制执行。）

3. 执行物理清理：重写历史后，必须执行垃圾回收才能真正释放磁盘空间。

   # 1. 清理filter-repo留下的旧引用
   git for-each-ref --format='delete %(refname)' refs/original | git update-ref --stdin
   # 2. 强制使所有旧记录过期
   git reflog expire --expire=now --all
   # 3. 执行垃圾回收（此步骤非常耗时，请勿中断）
   git gc --prune=now --aggressive

4. 验证结果：再次运行git filter-repo --analyze --force，确认目标文件已从报告中消失。
5. 强制推送：将重写后的历史推送到远程仓库。

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

6. 通知团队：所有开发者必须重新克隆仓库，不可基于本地旧历史进行提交，否则可能恢复已删除的数据。

为何不用 git rebase -i？

许多开发者会想到用git rebase -i来编辑提交以删除大文件。但这存在两个主要问题：

1. 适用范围有限：rebase -i擅长处理线性、近期的历史。对于散落在漫长历史中的大文件，操作极其繁琐低效。
2. 无法释放空间：即使通过rebase移除了对某文件的引用，该文件的数据对象（Blob）仍然物理存在于.git/objects目录、reflog或其它分支/标签中，仓库体积不会减小。要物理删除，仍需执行上述的gc清理步骤。

简而言之，git rebase -i是优秀的线性历史编辑工具，而git filter-repo是专业的全历史内容清理工具，两者解决的是不同维度的问题。

实践总结与思考

在实际操作中，采用方案二将一个2.2GB的仓库成功缩减至400MB。整个过程技术步骤虽然清晰，但物理清理（git gc）阶段耗时极长（可能长达数小时）且不容中断，需要做好充分准备。

这次清理更像“治标”，因为项目仍需要将带哈希的构建产物维护在仓库中，每次构建都会产生新文件，为未来的再次膨胀埋下隐患。要“治本”，必须从源头建立规范，明确代码仓库的准入流程，杜绝非源码文件（如构建产物、依赖包）的提交，才能从根本上解决仓库膨胀问题。