使用 Git LFS 管理大文件并上传至 GitHub

使用 Git LFS 管理大文件并上传至 GitHub 的完整实践

在嵌入式 SDK 或 BSP 项目中，经常包含工具链压缩包（如 .tar.xz、.img、.elf 等），这些文件远超 GitHub 的 100MB 限制。本文记录了完整的 Git LFS 配置、迁移和使用流程，适合用于大型 Linux SDK、芯片 BSP 上传。

🧱 一、什么是 Git LFS？

Git LFS（Large File Storage）是 Git 官方支持的大文件扩展，能够将大文件内容托管在 Git 仓库外部，同时只保存指针在 Git 中，大大减少仓库体积，并解决 GitHub 100MB 文件限制。

🔧 二、初次配置 Git LFS（只需一次）

bash 复制代码

# 安装 Git LFS（Linux 环境）
sudo apt install git-lfs
git lfs install

# 配置需要托管的文件类型（一次性添加）
git lfs track "*.img" "*.bin" "*.hex" "*.elf" "*.tar.gz" "*.tar.xz"

# 提交 .gitattributes 记录
git add .gitattributes
git commit -m "配置 Git LFS 跟踪大文件"

♻️ 三、迁移历史大文件为 LFS（首次上传前执行）

如果你的项目中之前已经提交了大文件，必须执行以下命令将历史记录中这些大文件转换为 Git LFS 托管：

ini 复制代码

git lfs migrate import --include="*.img,*.bin,*.hex,*.elf,*.tar.gz,*.tar.xz"

然后强制推送到远程仓库：

css 复制代码

git push origin master --force

📦 四、日常使用（添加新大文件）

配置完 Git LFS 后，后续添加 .img/.bin/... 等大文件时，无需额外操作，直接执行普通 Git 命令即可：

sql 复制代码

git add 路径/大文件
git commit -m "添加 xxx 大文件"
git push

LFS 会自动生效。

🔍 五、查看当前托管的 LFS 文件

复制代码

git lfs ls-files

📝 六、补充说明

如果新增新类型大文件（例如 .zip），需执行：

sql 复制代码

git lfs track "*.zip"
git add .gitattributes
git commit -m "新增 zip 类型到 Git LFS"

GitHub 限制单文件最大 100MB，未使用 LFS 上传超过此大小会被拒绝。
Git LFS 免费额度为每月 1GB 存储和 1GB 带宽（可扩展）。

✅ 七、问题与实战中踩过的坑

remote: error: GH001: Large files detected：说明未使用 LFS，需执行 git lfs track 并重新 commit。
.gitattributes 忘记提交：导致文件未触发 LFS 上传。
上传失败或 push 太慢：建议按子模块拆分上传、使用国内镜像、或自建 Git 服务。

🚀 八、建议配合使用的脚本（可选）

bash 复制代码

#!/bin/bash
# add_lfs_file.sh
git add "$1"
git commit -m "添加大文件 $1"
git push

📚 九、总结

步骤	是否必须	说明
git lfs install	✅ 一次性	安装并初始化 LFS
git lfs track	✅ 一次性	跟踪文件后缀（*.img等）
.gitattributes 提交	✅ 一次性	记录 LFS 跟踪规则
git lfs migrate import	⚠️ 如有历史大文件需执行	迁移旧记录为 LFS
git add/commit/push	✅ 每次使用	正常使用 Git 推送

希望这篇博客对你在嵌入式 SDK 或 Linux 项目上传至 GitHub 时有所帮助。如有更多问题欢迎留言交流！