bfg repo-cleaner是专为git仓库设计的快速清理工具，用scala编写，可高效移除历史中大于指定大小的文件（如--strip-blobs-bigger-than 100m）、特定文件（如*.class）及敏感文本，速度比git-filter-branch快10–720倍。
如果您在Mac上使用Git时发现项目仓库体积异常庞大，尤其是.git目录远超正常范围（如超过100MB），则很可能是历史提交中误存了大文件（如资源包、构建产物、日志、临时文件等），而这些文件虽已删除，却仍完整保留在Git对象数据库中。以下是针对macOS平台彻底清理Git历史大文件的多种可行方案：
一、使用git-filter-repo工具精准清除指定路径
git-filter-repo是当前官方推荐、macOS兼容性最佳的历史重写工具，取代已弃用的git filter-branch，避免shell转义问题，执行更稳定高效。它可安全删除特定文件或目录的全部历史记录。
1、通过pip安装工具：pip install git-filter-repo
2、进入仓库根目录，执行命令清除指定路径（例如删除wwwroot/lib/及其所有历史）：git filter-repo --path "wwwroot/lib/" --invert-paths --force
3、若需批量清除多个路径，可重复使用--path参数，如：git filter-repo --path "wwwroot/lib/" --path "wwwroot/css/*.min.css" --path "wwwroot/temp/" --invert-paths --force
4、执行后运行本地清理：git reflog expire --expire=now --all && git gc --prune=now --aggressive
5、验证效果：运行du -sh .git对比清理前后体积变化，务必确认输出中不再包含目标路径的blob对象
二、使用BFG Repo-Cleaner快速剥离超限二进制文件
BFG Repo-Cleaner专为大文件清理设计，无需编写复杂命令，对macOS原生支持良好，尤其适合按大小阈值批量剔除（如所有>10MB的文件），执行速度显著快于原生命令。
1、下载BFG工具：curl -O https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar
2、执行按尺寸清理（示例：移除所有大于10MB的文件）：java -jar bfg-1.14.0.jar --strip-blobs-bigger-than 10M
3、清理冗余引用并压缩对象库：git reflog expire --expire=now --all && git gc --prune=now --aggressive
4、检查残留：运行git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print $3, $4}' | sort -n -k1 | tail -5，确保最大文件尺寸已降至10MB以下
三、定位并手动清除历史中的最大对象
该方法不依赖第三方工具，仅使用Git原生命令定位具体大文件路径，适用于需精确控制清理范围或受限于环境无法安装额外工具的场景。
1、列出历史中体积最大的10个blob对象（适配macOS无numfmt）：git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print $3, $4}' | sort -n -k1 | tail -10 | awk '{ size = $1; if (size >= 1024*1024*1024) printf "%.2fGB %s\n", size/(1024*1024*1024), $2; else if (size >= 1024*1024) printf "%.2fMB %s\n", size/(1024*1024), $2; else if (size >= 1024) printf "%.2fKB %s\n", size/1024, $2; else printf "%dB %s\n", size, $2; }'
2、根据输出结果识别需清除的文件路径（如data/model.bin）
3、使用git filter-branch进行针对性清除（注意：仅限macOS Git Bash或iTerm2等兼容环境）：git filter-branch --tree-filter 'rm -f data/model.bin' --prune-empty -- --all
4、强制过期reflog并执行深度垃圾回收：git reflog expire --expire=now --all && git gc --prune=now --aggressive --auto
5、执行前必须备份仓库，因filter-branch在macOS高版本可能出现路径解析异常
四、预防性加固：配置.gitignore与Git LFS
清理完成后，须立即建立防护机制，防止同类问题复发。macOS用户应特别注意Finder隐藏文件、Xcode生成物及Homebrew相关缓存路径是否被意外纳入跟踪。
1、编辑项目根目录下的.gitignore文件，追加常见大文件模式：**/*.zip\n**/*.tar.gz\n**/build/\n**/dist/\n**/node_modules/\n**/wwwroot/lib/\n**/wwwroot/temp/\n*.DS_Store
2、对确需版本管理的大文件（如设计稿、音视频素材），启用Git LFS：git lfs install && git lfs track "*.psd" && git lfs track "*.mp4" && git add .gitattributes
3、验证LFS规则生效：git lfs ls-files应显示已注册的文件类型，此后所有匹配文件将仅存储指针，不再膨胀.git目录
五、强制同步远程仓库并通知协作者
本地清理完成仅解决单机问题，远程仓库仍保留旧对象。macOS用户需通过强制推送使远程瘦身，并确保团队成员正确重建本地环境。
1、执行强制推送所有分支与标签：git push origin --force --all && git push origin --force --tags
2、通知所有协作者立即执行以下操作：git fetch origin && git reset --hard origin/main && git clean -fd（假设主分支为main）
3、提醒协作者检查GitHub/GitLab远程设置：GitHub默认保留强制推送前的引用30天，需管理员手动进入Settings → Danger Zone → Delete all refs under refs/original/ 才能彻底释放空间
