GitHub 大文件推送避坑指南

步骤 4 · 强制推送到远程

由于本地仓库的历史记录已被重写，必须使用 --force 选项覆盖远程仓库的分支：

git push origin master --force

• 重要提示：如果远程分支（如 master）设置了保护规则，你可能需要先在 GitHub 仓库的 Settings → Branches 中临时禁用分支保护，才能执行强制推送。也可以尝试使用更安全的 --force-with-lease。

后续协作提醒

其他协作者在拉取更新前，需要执行：

git fetch --all
git reset --hard origin/master # 强制将本地分支重置到远程状态

或者，更推荐的做法是让协作者重新克隆仓库（git clone），以确保历史记录完全一致。克隆后，使用 git lfs pull 来拉取 LFS 管理的实际文件内容。

方案二：备选方法（不保留大文件历史）

如果不想使用 Git LFS，或者文件过大超出 LFS 配额限制，可以考虑以下方法。⚠️ 注意：这些方法会丢失该大文件在 Git 中的版本历史，仅保留最后一次提交的快照。

方法 A：彻底移除大文件历史 (git filter-repo / BFG)

使用强大的 git filter-repo 工具（需单独安装）从所有历史提交中删除指定的大文件：

git filter-repo --path data/wmt_zh_en_training_corpus.csv --invert-paths

• 此命令会彻底删除历史中该文件的记录，同样会改变所有相关提交的哈希值。
• 执行后，如果需要保留这个大文件的最新版本（但不再追踪其历史），可以重新添加它（并考虑用 LFS 或方法 B 处理），或者直接删除它。之后也需要强制推送 (git push --force)。

方法 B：分割大文件 + 外部存储

1. 分割文件：使用工具（如 Linux/macOS 的 split 命令或 Windows 的 7-Zip）将大文件分割成多个小于 100MB 的分片文件（例如 file.part1, file.part2）。
2. 提交分割文件：将这些小文件添加到 Git 仓库并提交。同时，添加一个 README.md 文件说明如何合并这些分片（例如使用 cat file.part* > original_file 或 7-Zip 解压）。
3. 或使用外部存储：将原始大文件上传至云存储服务（如 Google Drive, Dropbox, 腾讯云 COS 等），在仓库中提供一个下载链接的说明文件。

• 缺点：完全失去了对该文件的版本控制能力。使用者需要手动操作才能获得完整文件。

常见错误 & 注意事项

• 只删文件再提交无效：如果在本地删除了大文件然后提交，Git 历史中该文件之前的版本记录依然存在。必须使用 git lfs migrate 或 git filter-repo 等工具重写历史才能彻底解决。
• Git LFS 配额限制：GitHub 为免费用户提供的 Git LFS 存储空间为 1GB，每月带宽也为 1GB。对于非常大的文件或项目，可能需要购买 GitHub Pro/Team 套餐，或者考虑自建 LFS 服务器。
• 强制推送后的团队协作：强制推送 (git push --force) 会覆盖远程历史。务必通知所有协作者。建议他们备份本地更改后，重新克隆仓库 (git clone)，或者极其谨慎地使用 git fetch --force 配合 git reset --hard。
• 受保护分支：如果目标分支（如 master）在 GitHub 上受保护，默认禁止强制推送。需要在仓库的 Settings → Branches 中临时调整分支保护规则，或者使用 --force-with-lease（它会在覆盖前检查远程分支是否是你期望的状态，相对安全一些）。

极简回退操作（仅适用于未分享的、仅一次的误提交）

如果你刚刚不小心提交了一个大文件，并且还没有进行任何 git push 操作，也没有其他协作者拉取过你的这次提交，那么一个简单的回退方法是：

git reset --soft HEAD~1 # 撤销上一次提交，但保留工作区的文件改动

撤销后，你可以按照方案一的步骤（安装 LFS、跟踪文件、添加 .gitattributes、提交），或者用 git rm --cached 彻底移除大文件（如果不需要它）后再做一次新的提交。然后正常推送（无需强制）。

完整命令速查表 (Git LFS 方案)

# 1. 初始化 LFS
git lfs install

# 2. 跟踪大文件 (以 .csv 为例，根据实际情况修改)
git lfs track "*.csv"
git add .gitattributes
git commit -m "setup lfs"

# 3. 迁移历史中的大文件 (替换路径)
git lfs migrate import --include="data/*.csv" --everything
# 或者只针对单个文件
# git lfs migrate import --include="data/wmt_zh_en_training_corpus.csv" --everything

# 4. 强制推送
git push origin master --force

# 5. 验证
git lfs ls-files