Git LFS 大文件清理

什么时候会用到

Push 或 clone 时若出现 lfs batch error、LFS only supported 一类报错，往往是大文件被 Git LFS 追踪，而远程（例如 Gitee 个人版、GitHub Free 某些场景）并不提供可用的 LFS 服务。模型权重（*.safetensors、*.bin、*.pt）、压缩包、.venv/、node_modules/ 或 Hugging Face / ModelScope 缓存一旦被 LFS 指针写进历史，仓库体积和 push 失败会一起找上门。

技能如何组织排查与修复

技能按固定顺序做诊断：先确认是否为 LFS 问题，再用 git lfs ls-files 看追踪列表（* 表示已上传的指针），并在工作区扫描超过 10MB 的文件；同时核对 .gitignore 与 .gitattributes 里的 track 规则是否把本不该进库的内容纳了进来。

处理上分两条路。方案 A（推荐）：在 .gitignore 里只排除真正不需要版本控制的目录 → git rm --cached 从索引移除（不删本地文件）→ 清理 LFS 追踪 → 若 git lfs migrate export 因远程 LFS 不可用而失败，则用 git-filter-repo 从历史中彻底去掉大文件路径 → 重新添加 origin 并 force push。方案 B：若大文件尚未 push、也无需改历史，则 .gitignore + 取消暂存即可。

边界与协作成本

git-filter-repo 会重写全部历史，协作者通常需要重新 clone；git rm --cached 与 --invert-paths 不会删磁盘上的文件。若远程 LFS 正常，migrate export 可优先尝试以保留内容并取消 LFS 管理。另需注意：git lfs uninstall 后仍报错时要清 local/global 的 filter.lfs；filter-repo 的 --path 不能含空格；Windows 上偶现 unable to unlink 警告一般可忽略。