🚀 Git 仓库终极瘦身指南：使用 git-filter-repo 完美剔除历史大文件

背景痛点

接手同事的旧项目，发现源码只有 100 多 M，但整个 Git 仓库却高达 2.6G！直接在工作区删除大文件并 commit 毫无作用，因为 Git 的核心机制是“记住一切”，大文件依然死死躺在 .git 的历史记录里。当你想把项目迁移到新仓库时，那 2.6G 的历史包袱也会跟着一起推上去。

本文将教你如何使用官方推荐的终极武器 git-filter-repo，彻底改写 Git 历史，剔除不需要的大文件和冗余分支，干干净净地迁移到新仓库。

⚠️ 第一步：防翻车准备（非常重要）

操作前，务必把当前的本地项目文件夹复制备份一份！ 修改 Git 历史属于破坏性操作，一旦误操作会导致代码丢失。做好备份，我们就可以大胆折腾。

第二步：安装工具

git-filter-repo 是目前 Git 官方推荐的历史重写工具，依赖 Python。

在终端执行以下命令安装：

# 使用 pip 安装
pip install git-filter-repo

# macOS 用户也可以使用 brew
brew install git-filter-repo

第三步：执行“剔骨”清理

进入你的项目根目录。你可以根据实际需求，选择按大小或者按路径清理。

情况 A：精准删除特定目录或文件（例如冗余的 ISO 文件或 .idea 配置）

# --path 指定要删除的路径，--invert-paths 表示反向选择（即剔除该路径）
# --force 用于强制执行（防止工具提示非全新 clone 而拒绝工作）
git filter-repo --path tinyLinuxISO --invert-paths --force
git filter-repo --path raidConfigure_linux --invert-paths --force
git filter-repo --path .idea --invert-paths --force

💡 技巧：你可以使用多个 --path 一次性干掉多个目标。

情况 B：简单粗暴按大小清理

# 剔除历史记录中所有大于 50M 的文件
git filter-repo --strip-blobs-bigger-than 50M --force

执行完毕后，使用 ls -a 查看，目标文件已彻底消失，且项目体积大幅缩水！

第四步：整理分支，重命名为 main

以前的代码可能有一堆乱七八糟的本地分支，趁着这次净化，我们只留一条主线，并统一命名为 main。

# 切换到你想要保留的主分支（假设原先叫 master）
git checkout master

# 将当前分支重命名为 main
git branch -m main

第五步：重新绑定远程仓库并推送

🔥 避坑高能预警： git-filter-repo 出于安全保护机制，在重写历史后，会自动删除你本地关联的远程仓库地址（origin）。如果你直接 push，会报 fatal: 'origin' does not appear to be a git repository 的错误。

所以，我们需要重新绑定新仓库，然后单独推送 main 分支：

# 1. 重新绑定你新建的纯净远程仓库地址
git remote add origin http://你的Git地址/你的项目.git

# 2. 将本地的 main 分支推送到远端（仅推送这一条线，抛弃其他旧分支）
git push -u origin main

如果中间你又发现漏删了什么东西（比如刚推上去又自动生成了 .idea），重新走一遍第三步清理后，使用强制推送覆盖远程记录即可：

# 强行覆盖远程仓库
git push -u origin main -f

第六步：亡羊补牢，配置 .gitignore

为了防止编辑器或系统再次生成垃圾文件（如 .idea, .DS_Store）并被提交，务必在项目根目录创建或更新 .gitignore 文件：

.idea/
*.log
# 其他不需要追踪的文件...