github单个文件超100mb限制时，应优先启用git lfs：执行git lfs install、git lfs track指定文件类型、git add .gitattributes和大文件、commit后push；若历史已含大文件，需用git filter-repo清理并git lfs migrate重写；缓冲区不足可调http.postbuffer；不可分二进制文件必须用lfs，可分文件可split上传；未推送前可用git reset--soft和git rm--cached撤销。
如果您尝试将大文件推送到 GitHub 仓库，但收到 remote: error: File xxx is XXX MB; this exceeds GitHub's file size limit of 100.00 MB 报错，则说明该文件已超出 GitHub 对单个文件的硬性大小限制。以下是针对此问题的多种解决路径：
一、启用 Git LFS 管理大文件
Git LFS 是 GitHub 官方推荐的解决方案，其原理是将大文件本体替换为轻量级指针，实际文件存储在独立的 LFS 服务器上，Git 仓库仅保留元数据和版本引用，从而规避 100MB 限制。
1、在项目根目录打开终端，执行 git lfs install 初始化本地 LFS 客户端。
2、指定需由 LFS 跟踪的文件类型，例如：执行 git lfs track "*.pth" 跟踪所有 PyTorch 模型文件；或执行 git lfs track "*.zip" 跟踪压缩包；如需覆盖全部大文件，可运行 git lfs track "*"。
3、执行 git add .gitattributes 将生成的配置文件加入暂存区。
4、执行 git add （如 git add models/vgg16.pth）显式添加目标大文件。
5、执行 git commit -m "add large files via LFS" 提交变更。
6、执行 git push origin <branch></branch> 推送，Git LFS 将自动上传大文件至 LFS 服务端。
二、清理历史提交中的大文件
若此前已多次提交过大文件并推送失败，或错误地将大文件纳入了 Git 历史记录，则单纯启用 LFS 无法生效，必须清除历史中的大文件对象，否则远程仍会拒绝推送。
1、安装 BFG Repo-Cleaner 工具（需 Java 环境），或使用原生命令 git filter-repo（推荐，需先通过 pip install git-filter-repo 安装）。
2、执行 git filter-repo --path --invert-paths --force 删除指定路径文件在全部历史中的痕迹。
3、执行 git lfs migrate import --include="*.pth,*.zip" --everything 将符合条件的大文件从历史中提取并重写为 LFS 引用。
4、强制推送重写后的历史：git push --force --all origin 和 git push --force --tags origin。
三、临时增大 HTTP 缓冲区规避传输中断
部分推送失败并非因文件超限，而是因网络不稳定导致 Git 在传输大文件时触发默认缓冲区溢出，表现为连接中断或 early EOF 错误。此方法不解除 100MB 限制，但可提升大文件（尤其接近 100MB 的文件）成功上传概率。
1、在项目所在仓库执行 git config http.postBuffer 524288000，将 HTTP POST 缓冲区设为 500MB。
2、验证配置是否生效：运行 git config --get http.postBuffer，应返回 524288000。
3、重新执行 git add、git commit 和 git push 流程。
四、手动拆分大文件后分别上传
对于不可分割的二进制文件（如模型权重、ISO 镜像），Git LFS 是唯一合规方案；但对可分割的文本类或归档类文件（如日志、数据库导出），可通过外部工具将其切片，再以普通 Git 方式上传，避免触发限制机制。
1、使用 split 命令（Linux/macOS）或 7-Zip（Windows）将大文件分割为多个小于 100MB 的片段，命名如 data.zip.001、data.zip.002。
2、执行 git add data.zip.* 添加全部分片。
3、执行 git commit -m "split and upload large archive" 提交。
4、执行 git push origin <branch></branch> 推送所有分片。
5、使用者需在本地合并还原：cat data.zip.* > data.zip（Linux/macOS）或使用 7-Zip 合并（Windows）。
五、回退并撤销错误提交
当刚执行 git commit 将大文件纳入暂存但尚未推送时，应立即撤销该提交，防止大文件进入本地历史，为后续 LFS 配置扫清障碍。此操作保留工作区文件，仅移除提交记录。
1、执行 git reset --soft HEAD^ 回退至上一提交，保留所有已修改/新增文件在暂存区。
2、执行 git rm --cached （如 git rm --cached dataset/cifar-10-python.tar.gz）取消大文件在 Git 中的跟踪。
3、完成 Git LFS 配置后，再执行 git add 交由 LFS 处理。
4、执行 git commit -m "add large file via LFS" 重新提交。
