Git 仓库“减肥”指南：从检测、清理到同步的全流程实践

随着项目的迭代，Git 仓库可能会因为错误提交大文件或历史记录过于冗长而变得异常臃肿。这会严重影响 clone、fetch 等操作的效率。本文档整理了一套完整的解决方案，用于安全、彻底地清理 Git 仓库，并指导团队成员如何同步更新。

核心警告：重写历史的风险

在开始之前，必须明确：清理 Git 仓库的核心是重写历史，这是一项具有破坏性的危险操作。

警告！ 重写历史会改变几乎所有受影响 commit 的哈希值（SHA-1 ID）。当你将修改后的历史强制推送到远程仓库时：

所有协作者的本地仓库将与远程仓库产生严重冲突。

基于旧 commit 创建的分支、Tag 和 Pull Request 将会失效或错乱。

因此，在对共享仓库执行这些操作前，必须与所有团队成员沟通，并协调一个统一的同步时间点和方案。

第一步：分析仓库，找出"元凶"

在动手清理之前，我们首先需要定位到是哪些文件或对象占用了最多的空间。

使用以下命令可以列出仓库中体积最大的前 20 个对象：

bash 复制代码

git rev-list --objects --all | \
git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
sed -n 's/^blob //p' | \
sort --numeric-sort --key=2 | \
tail -n 20

这个命令会输出对象的哈希值、体积（字节）和对应的文件路径，让你对仓库中的大文件一目了然。

第二步：清理历史，移除大文件

定位到大文件后，我们需要使用特定工具将其从所有历史记录中彻底抹去。

官方推荐工具：git-filter-repo

git-filter-repo 是 git filter-branch 的现代化替代品，它更安全、更快速、更易用。

1. 安装 git-filter-repo

bash 复制代码

pip3 install git-filter-repo

#或者直接brew 安装
brew install git-filter-repo

2. 执行清理操作

建议： 在执行清理前，先将你的项目完整备份一份，以防万一。

你可以根据需要选择不同的清理策略：

按文件大小移除（最常用）：

bash 复制代码

# 移除所有大于 10MB 的文件
git filter-repo --strip-blobs-bigger-than 10M

按文件名/路径移除（更精确）：

bash 复制代码

# 移除单个指定文件
git filter-repo --path 'path/to/your/large-file.zip' --invert-paths

# 移除整个目录
git filter-repo --path 'path/to/large-directory/' --invert-paths

3. 常见问题："Fresh Clone" 错误

在执行 git-filter-repo 时，你很可能会遇到以下错误：

vbnet 复制代码

Aborting: Refusing to destructively overwrite repo history since
this does not look like a fresh clone.
Please operate on a fresh clone instead.

这是 git-filter-repo 的一项安全机制，旨在防止在含有本地修改的"不干净"仓库中误操作。

推荐的解决方案： 按照提示，重新克隆一份仓库，并在新的"干净"仓库中执行清理命令。
bash 复制代码
```
cd ..
git clone /path/to/your/repo my-repo-fresh
cd my-repo-fresh
# 在这里执行 git-filter-repo 命令...
```
强制执行方案： 如果你确信当前仓库没有需要保留的本地修改，可以使用 --force 标志跳过检查。
bash 复制代码
```
git filter-repo --force --strip-blobs-bigger-than 10M
```

第三步：完成清理并强制推送

git-filter-repo 执行完毕后，你的本地历史已被重写。现在需要将这些变更同步到远程仓库。

回收空间 ：git-filter-repo 通常会自动处理清理，但可以手动执行一次 gc 来确保空间被回收。
bash 复制代码
```
git gc --prune=now --aggressive
```

强制推送：这是覆盖远程仓库历史的关键一步。

bash 复制代码

# --force: 强制推送
# --all: 推送所有本地分支
git push origin --force --all

# 同时强制推送所有标签
git push origin --force --tags

第四步：团队成员如何同步？

当管理员完成强制推送后，所有团队成员的本地仓库都已"过时"，必须进行同步。

方案A（最简单，强烈推荐）：重新克隆

这是最安全、最不容易出错的方法。

删除本地的旧仓库文件夹。
从远程重新克隆一份全新的仓库：git clone <repository_url>。

方案B（高级，修复现有分支）：使用 Rebase

如果你本地有不想丢失的开发中分支，可以尝试此方法。对你的每一个本地分支，执行以下操作：

假设被重写的远程主分支是 main，你的本地开发分支是 feature/a。

获取最新的远程历史：
bash 复制代码
```
git fetch --all --prune
```
切换到你的本地分支：
bash 复制代码
```
git checkout feature/a
```
将分支"嫁接"到新的主分支上：
bash 复制代码
```
git rebase origin/main
```
- 如果出现冲突，需要手动解决，然后 git add . 并 git rebase --continue。
- 如果想放弃，可使用 git rebase --abort。

强制推送你的分支 ：因为 rebase 也重写了你分支的历史，所以也需要强制推送。

bash 复制代码

# 使用 --force-with-lease 更安全，可以防止覆盖他人无意中推送的更新
git push origin feature/a --force-with-lease

补充知识点：被忽略的文件（.gitignore）会受影响吗？

答案：完全不会。

Git 的所有历史操作（包括 filter-repo 和 rebase）都只作用于已被 Git 跟踪（Tracked）的文件。

.gitignore 文件中列出的文件和目录，Git 从一开始就不会跟踪它们。它们只存在于你的本地文件系统，不存在于 Git 的版本历史中，因此在整个清理过程中它们会原封不动地待在原地，十分安全。