Git LFS 大文件清理

诊断流程

收到用户报错后，按以下顺序排查：

1. 确认是否为 LFS 问题：查看错误信息是否包含 lfs batch error、LFS only supported 等关键字
2. 定位 LFS 文件：git lfs ls-files 查看被 LFS 追踪的文件（* 表示已上传的指针文件）
3. 扫描大文件：在项目目录中查找超过 10MB 的文件，重点关注：
• .safetensors、.bin、.pt、.onnx（模型权重）
• .tgz、.tar.gz、*.zip（压缩包）
• .venv/、node_modules/（依赖目录）
• huggingface_cache/、modelscope_cache/（模型缓存）
4. 检查 .gitignore：确认大文件目录是否已被排除
5. 检查 .gitattributes：确认 LFS track 规则

处理方案

方案 A：取消 LFS 追踪 + .gitignore 排除（推荐）

适用于 Gitee 个人版、GitHub Free 等不支持 LFS 的远程仓库。

Step 1: 更新 .gitignore

在 .gitignore 中添加需要排除的大文件目录。通用规则：

# AI 模型缓存
huggingface_cache/
modelscope_cache/

# Python 虚拟环境
.venv/
venv/

# 数据集
data/dataset/
data/images/

# 大文件类型
*.safetensors
*.tar.gz
*.tgz

根据实际项目结构调整，只排除真正不需要版本控制的目录。

Step 2: 从 git 索引移除（不删本地文件）

git rm --cached -r <目录或文件路径>

Step 3: 清理 LFS 追踪

# 取消 LFS 追踪
git lfs untrack "*"

# 卸载 LFS hooks
git lfs uninstall

# 清理残留 filter 配置
git config --unset filter.lfs.clean
git config --unset filter.lfs.smudge
git config --unset filter.lfs.process
git config --remove-section lfs
# 全局配置也要清理
git config --global --unset filter.lfs.clean
git config --global --unset filter.lfs.smudge
git config --global --unset filter.lfs.process

Step 4: 用 git-filter-repo 从历史中彻底删除大文件

如果 git lfs migrate export 失败（常见原因：远程 LFS 服务不可用，无法下载指针指向的实际文件），必须用 filter-repo。

# 安装（如果没有）
pip install git-filter-repo

# 从所有历史提交中删除指定路径
python -m git_filter_repo --invert-paths \
  --path AI/HuggingFace \
  --path AI/ModelScope \
  --path .venv \
  --path data/dataset \
  --force

注意：git-filter-repo 会自动移除 origin remote，需重新添加。

Step 5: 重新关联远程并 force push

# filter-repo 会删除 origin，需重新添加
git remote add origin <仓库URL>

# force push（历史已重写，必须强制推送）
git push --force origin <分支名>

方案 B：仅 .gitignore 排除（LFS 文件未在历史中）

如果 LFS 文件只是 git add 了但还没 push，且不需要清理历史：

# 更新 .gitignore
# 从索引移除
git rm --cached -r <路径>
# 正常提交推送
git add .gitignore
git commit -m "chore: remove large files from tracking"
git push

注意事项

• git-filter-repo 会重写所有历史，所有协作者需要重新 clone
• 本地文件不受影响，git rm --cached 和 filter-repo --invert-paths 只影响 git 追踪，不删除磁盘文件
• 如果 git lfs migrate export 可用（远程 LFS 服务正常），优先使用它，可以保留文件内容但取消 LFS 管理
• force push 前确认没有其他协作者正在使用该仓库，或提前通知他们
• Windows 下 git-filter-repo 可能出现 unable to unlink 警告，可忽略，不影响结果

常见踩坑

• git lfs uninstall 后仍报 LFS 错误：需要手动清理 git config 中的 filter.lfs 配置（local + global）
• git lfs migrate export --include="*" 失败：通常是因为需要从远程下载 LFS 对象但远程不支持，此时必须用 git-filter-repo
• git-filter-repo 不支持 --path 包含空格的路径，确保路径无空格
• Gitee 个人版不支持 LFS，如果不想升级企业版，唯一解法是从历史中彻底移除 LFS 文件