当前位置：首页 > news >正文

git-filter-repo 清除大文件教程

news 来源：原创 2025/5/17 21:03:08

git filter-repo 是一个用于过滤和清理 Git 仓库历史的工具，它可以高效地批量修改提交历史中的文件内容、删除文件、重命名文件以及进行其他历史重构操作。相较于 git filter-branch，它通常更快且更易于使用。

以下是一个基本示例，说明如何使用 git filter-repo 来删除仓库中特定的大文件：

安装 git-filter-repo

首先确保你已安装 Python，并且可以通过 pip（Python 的包管理器）来安装软件包。如果没有安装 Python 和 pip，需要先安装它们。
使用 pip 安装 git-filter-repo：

python -m pip install --user git-filter-repo  # 对于个人用户安装
# 或者全局安装（可能需要管理员权限）
python -m pip install git-filter-repo

安装完成后，你可以直接使用 git-filter-repo 命令。但由于它并非 Git 内置命令，你需要在终端中直接调用它的路径或者将它的安装目录添加到系统 PATH 环境变量中。例如，在 Unix/Linux 系统中，如果 git-filter-repo 已经被安装在 ~/.local/bin/ 目录下，你可以通过如下命令临时添加到 PATH 中：

export PATH=$PATH:~/.local/bin/

win11

C:\Users\w8\AppData\Roaming\Python\Python311\site-packages

既然 git-filter-repo 已经安装完毕，接下来你可以直接在命令行中使用它。但是请注意，在 Windows 系统中，可能需要将 git-filter-repo 的安装路径添加到系统的 PATH 环境变量，以便能在任何目录下执行这个命令。

若要在当前终端会话中临时添加到 PATH，可以运行以下命令（请替换实际的路径）：

set PATH=%PATH%;C:\Users\w8\AppData\Roaming\Python\Python311\Scripts

如果希望永久生效，你需要编辑系统的环境变量设置：

右键点击“计算机”或“此电脑”，选择“属性”。
在左侧菜单栏选择“高级系统设置”。
在“系统属性”窗口中点击“环境变量”按钮。
在“系统变量”区域找到名为 Path 的变量，选中后点击“编辑”。
在“编辑环境变量”窗口中，点击“新建”按钮，然后添加 C:\Users\w8\AppData\Roaming\Python\Python311\Scripts 这个路径。
点击“确定”保存所有更改。

完成以上步骤后，你应该能够在命令行中直接运行 git filter-repo 命令了

删除仓库历史中的大文件

假设你想删除历史记录中所有包含名为 large_file.txt 的文件，并且你知道这个文件存在于所有的提交中。

首先备份你的仓库，以防万一：
```
1cp -r your_repo your_repo_backup
```
进入要处理的仓库目录：
```
1cd your_repo
```
使用 git filter-repo 删除指定文件：
```
1git filter-repo --force --invert-paths --path large_file.txt
```
参数解释：
- --force：允许覆盖当前仓库。
- --invert-paths：保留不匹配路径的提交，这里是反选，即删除匹配路径的文件。
- --path large_file.txt：指定要从历史中删除的文件名。

清理并优化本地仓库：

1git reflog expire --all --expire-unreachable=now --update-reflogs
2git gc --prune=now --aggressive

推送更改到远程仓库（如果必要的话）：
```
1git push origin --force --all
2git push origin --force --tags
```
注意：由于你改变了历史记录，所以需要用 --force 强制推送，并通知协作者他们需要重新克隆更新后的仓库。

其他高级用法

除了删除文件外，git filter-repo 还可以实现更多的功能，例如：

删除符合某种模式的所有文件：

1git filter-repo --force --path-glob '*.zip'

替换文件内容：
```
1git filter-repo --replace-text <replacement-file>
```
在 <replacement-file> 中定义替换规则。
根据大小过滤文件：
```
1git filter-repo --strip-blobs-bigger-than 10M
```
删除大于10MB的二进制文件。
更多复杂操作，请参考官方文档：https://github.com/newren/git-filter-repo/blob/main/README.md