使用 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
),需执行:sqlgit 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 时有所帮助。如有更多问题欢迎留言交流!