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

相关推荐
巫山老妖9 小时前
Linux流量分析:tcpdump&wireshark
linux·嵌入式
不脱发的程序猿10 小时前
Linux守护进程
linux·嵌入式
desssq1 天前
嘉立创黄山派下载watch ui demo 教程(sf32)
ui·嵌入式·嘉立创·黄山派
趣多多代言人1 天前
从零开始手写嵌入式实时操作系统
开发语言·arm开发·单片机·嵌入式硬件·面试·职场和发展·嵌入式
DIY机器人工房1 天前
代码详细注释:通过stat()和lstat()系统调用获取文件的详细属性信息
linux·嵌入式
DIY机器人工房1 天前
代码详细注释:ARM-Linux字符设备驱动开发案例:LCD汉字输出改进建议开发板断电重启还能显示汉字,显示汉字位置自定义
linux·嵌入式·文件io·diy机器人工房
brave and determined2 天前
国产MCU学习Day11——CW32F030C8T6 低电压检测器(LVD)详解与应用
单片机·嵌入式硬件·嵌入式·国产mcu·cw32f030c8t6·cw32f030c8t6lvd·低电压检测器
KaiGer6663 天前
AUTOSAR进阶图解==>AUTOSAR_SWS_V2XFacilities
单片机·汽车·嵌入式·autosar
kyle~4 天前
计算机视觉---RealSense深度相机技术
人工智能·数码相机·计算机视觉·机器人·嵌入式·ros·传感器