TorchChat项目Git仓库大文件清理实践

在开源项目开发过程中，随着时间推移，Git仓库中可能会积累一些大文件，这些文件会显著增加仓库体积，影响克隆和操作速度。本文以TorchChat项目为例，介绍如何识别和清理Git历史中的大文件。

问题背景

TorchChat项目在开发过程中，由于测试需要，在checkpoints/stories15M目录下存放了一些大模型文件，这些文件被意外提交到了Git仓库中。这些文件包括：

• 60MB左右的模型二进制文件(stories15M.bin和stories15M.pt)
• 57MB的编译对象文件(clao3uuulhp55qvru3odpuqyjekkp2p7xmr3epbkgn5tgy4prx4f.o)
• 其他各种中间文件和检查点文件

这些大文件虽然已经被删除，但仍然存在于Git历史记录中，导致仓库体积膨胀。

解决方案

1. 识别大文件

首先需要识别Git历史中的大文件。可以通过以下命令查看：

git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | grep -v '^tree' | sort -k3 -n -r | head -n 10

这个命令会列出Git历史中最大的10个文件。

2. 使用filter-branch清理历史

对于TorchChat项目，我们使用git filter-branch命令来清理checkpoints/stories15M目录下的所有文件：

git filter-branch -f --index-filter 'git rm --force --cached -r --ignore-unmatch checkpoints/stories15M/' -- --all

这个命令会重写Git历史，从所有分支中删除指定目录下的文件。其中：

• --index-filter：指定在索引上执行的操作
• git rm --force --cached -r --ignore-unmatch：强制删除缓存中的文件，忽略不匹配的情况
• -- --all：对所有分支和标签进行操作

3. 清理效果

执行上述命令后，仓库体积从80MB左右下降到3.9MB，效果显著。命令执行过程中会重写所有分支的历史记录，确保大文件被彻底清除。

注意事项

1. 备份：在执行历史重写操作前，务必备份整个仓库，因为操作是不可逆的。

2. 协作影响：历史重写会影响所有协作者，需要通知团队成员重新克隆仓库或在本地执行特定命令来同步变更。

3. 残留文件：即使执行了清理，项目中仍可能存在其他大文件，如临时文件等，需要定期检查清理。

4. 替代工具：对于大型项目，可以考虑使用BFG Repo-Cleaner等专门工具，它们比git filter-branch更高效。

最佳实践建议

1. .gitignore配置：在项目初期就配置好.gitignore文件，避免将大文件或临时文件提交到仓库。

2. Git LFS：对于必须版本控制的大文件，考虑使用Git LFS(Git Large File Storage)来管理。

3. 定期检查：建立定期检查仓库大小的机制，及时发现并处理大文件问题。

4. 提交规范：制定清晰的提交规范，避免将生成文件或中间产物提交到版本控制。

通过以上措施，可以有效控制Git仓库体积，提高开发效率。TorchChat项目的这次清理实践为类似项目提供了很好的参考案例。