[GIT] git lfs：大文件的版本管理

1 概述: Git LFS

• Git LFS（Large File Storage）是 Git 的一个扩展，核心特性在于用“【文本指针】”替换【大文件】，并将【文件实体】存储在【远程服务器】上，从而解决 Git 仓库膨胀、克隆过慢的问题。

• 主要特性包括：

• 优化性能：仓库仅包含轻量级的指针文件。克隆和拉取操作默认只下载当前检出版本的文件，而非全量历史，大幅节省时间和磁盘空间。
• 透明交互：通过 Git 钩子自动工作。用户日常使用 git add、commit、push 时感觉不到差异，LFS 会在后台自动处理大文件上传和下载。
• 文件锁定：支持文件锁定功能。通过 git lfs lock 锁定二进制文件（如图片、模型），防止团队成员产生无法自动合并的冲突，适合美术、策划等非代码资产协作。
• 精细追踪：通过 .gitattributes 文件配置规则（例如 *.psd filter=lfs diff=lfs merge=lfs），可以按文件类型、名称或目录精确控制哪些文件走 LFS 传输，支持将历史中的大文件迁移至 LFS。

Z FAQ for git lfs

Q: 如果git不存储历史commit的大文件，git lfs 如何确保2次commit中的文件是一样的，还是不同的?

你的理解很准确：Git LFS 并没有丢弃历史版本的大文件，只是把它们移出了 Git 仓库本体，放到了独立的 LFS 存储中。判断两个 commit 里的文件是否相同，靠的是指针文件中的内容哈希。

1. 指针文件记录唯一标识

当一个大文件被 LFS 追踪时，Git 仓库中存储的是一个文本指针文件，例如：

version https://git-lfs.github.com/spec/v1
oid sha256:4e7d2e290f6c9a1c9d3e2a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d
size 123456

· oid 是文件内容的 SHA-256 哈希值，内容不同则哈希不同。
· 这个指针文件本身非常小（约 130 字节），它的内容完全由文件内容的哈希决定。

2. Git 比较的是指针内容

当你在两个 commit 之间比较同一个文件时：

· 如果文件内容没变 → 哈希不变 → 指针文件内容完全相同 → Git 认为文件没有变化。
· 如果文件内容变了 → 新内容生成新的哈希 → 指针文件内容改变 → Git 检测到文件被修改。

因此，虽然 Git 仓库里没有大文件的二进制内容，但指针文件忠实地反映了每个版本的大文件是否相同。

3. 历史版本的大文件保存在 LFS 存储中

LFS 服务器（或本地缓存）会以哈希为文件名存储所有曾提交过的大文件版本。当你切换到某个旧 commit 时，LFS 客户端会根据指针文件里的哈希自动下载对应版本的大文件。

所以，Git LFS 在版本判断上依赖内容寻址，确保了版本控制的完整性和准确性。

Q: set GIT_LFS_SKIP_SMUDGE=1是什么意思?

问题描述

使用 Git LFS 的跳过下载 huggingface 大文件

# 先安装 Git LFS
git lfs install

# 为避免 Git LFS (Large File Storage) 下载失败的问题，导致类似报错: `dial tcp: lookup cas-bridge.xethub.hf-mirror.org: no such host`( LFS 文件的存储域名无法解析)
## windows cmd
set GIT_LFS_SKIP_SMUDGE=1

# 克隆模型仓库 到指定目录下
git clone https://huggingface.co/BAAI/bge-m3 D:\Program-Data\ai-models\bge-m3

GIT_LFS_SKIP_SMUDGE=1 是什么意思?

问题分析

• smudge，英译: n.污点,污迹;vt. 弄脏，留下污迹
• GIT_LFS_SKIP_SMUDGE=1 是一个环境变量设置，用于控制 Git LFS（Large File Storage）的行为。

具体含义

术语	解释
smudge	Git LFS 的一个过滤器，负责在 git checkout 时将 LFS 指针文件替换为实际的大文件内容
GIT_LFS_SKIP_SMUDGE=1	设置后，跳过 smudge 过程，即不下载实际的大文件，只保留 LFS 指针文件

工作原理对比

正常克隆 (不设置)：
  LFS指针文件 ──→ smudge过滤器 ──→ 下载实际大文件 ──→ 你得到完整文件
                          ↑
                    从你的错误来看，这一步失败了
                          
设置 GIT_LFS_SKIP_SMUDGE=1 后：
  LFS指针文件 ───────────────────────→ 直接保留指针，不下载实际文件

指针文件长什么样？

• 克隆后你会看到类似这样的小文件（而不是实际模型）：

$ cat colbert_linear.pt
version https://git-lfs.github.com/spec/v1
oid sha256:19bfbae397c2b7524158c919d0e9b19393c5639d098f0a66932c91ed8f5f9abb
size 2100000

这只是 LFS 的元数据，记录了：

• 文件版本
• SHA256 校验值
• 实际文件大小

使用场景

场景	是否适合设置
只需要代码/配置文件，不需要模型权重	✅ 适合
网络不稳定，LFS下载总是失败	✅ 适合（先跳过，后续再单独下载）
磁盘空间有限	✅ 适合
需要完整运行模型	❌ 不适合（后续必须补下载）

后续如何补下载？

• 如果你跳过了 LFS 下载，之后可以用以下方式补下：

# 方法1：使用 git lfs pull 单独拉取大文件
cd bge-m3
git lfs pull

# 方法2：手动下载特定文件
git lfs fetch --include="colbert_linear.pt"

# 方法3：使用 huggingface-cli 单独下载（推荐，更稳定）
huggingface-cli download BAAI/bge-m3 --local-dir ./bge-m3 --local-dir-use-symlinks False

总结

GIT_LFS_SKIP_SMUDGE=1 = "先给我仓库的框架，大文件我稍后自己想办法"

这正好解决你遇到的 no such host 问题——绕过那个连不上的 LFS 服务器，先把能下的下了。

Y 推荐文献

X 参考文献

• Hugging Face : 开源大模型社区 | 机器学习（ML）和数据科学平台和社区、AI领域的Github - 博客园/数据知音