【Git】git lfs (Large File Storage)-管理大文件

Git LFS (Large File Storage) 是 Git 的一个扩展，用于高效管理大文件（如图像、音频、视频、数据集、二进制文件等）。它能解决传统 Git 在处理大文件时面临的核心问题：仓库体积急剧膨胀、克隆和拉取操作变得极其缓慢。

传统 Git 处理大文件的痛点：

1. 仓库膨胀： 每次修改大文件，即使只改了一点，Git 也会存储整个文件的新副本。历史记录中积累多个版本会快速耗尽磁盘空间。
2. 克隆/拉取缓慢： 克隆或拉取仓库时，必须下载整个历史记录中的所有文件版本，包含那些巨大的历史文件。
3. 性能下降： 提交、推送、拉取、切换分支等操作涉及处理大量二进制差异时非常慢。
4. 平台限制： Git 本身对大文件（尤其是频繁修改的）支持不佳，可能遇到内存或文件大小限制。

Git LFS 的工作原理：

1. “指针”替换： 当你 git add 一个大文件时（该文件类型已被 LFS 跟踪），Git LFS 会拦截这个操作。
2. 本地存储： 将大文件的真实内容存储在本地的 Git LFS 缓存区（通常在 .git/lfs/objects 目录下）。
3. 创建指针： 在 Git 仓库中，只存储一个轻量级的文本指针文件（约 1KB）。这个指针包含：
   • LFS 版本信息 (version https://git-lfs.github.com/spec/v1)
   • 文件的唯一标识符 (oid sha256:...)
   • 文件的实际大小 (size 123456789)
4. 推送： 当你 git push 时：
   • 像往常一样推送提交历史（包含指针文件）。
   • Git LFS 客户端会将本地缓存的大文件内容推送到配置的 LFS 存储服务器（通常是 Git 托管服务商如 GitHub, GitLab, Bitbucket 等提供的专用 LFS 存储，也可以是自建的）。
5. 克隆/拉取： 当你 git clone 或 git pull 时：
   • 先下载 Git 历史（包含指针文件）。
   • Git LFS 客户端检测到指针文件，并根据指针中的信息（oid, size）按需从 LFS 存储服务器下载对应的大文件真实内容到本地缓存。
   • 你的工作目录中看到的是完整的文件（LFS 通过 smudge 过滤器自动用真实内容替换了指针）。

核心优势：

• 小仓库体积： Git 仓库本身只存储轻量级指针，体积保持小巧。
• 快速克隆/拉取： 初始操作只下载指针和历史，速度极快。大文件按需下载。
• 高效历史： 历史记录清晰，只记录指针的变化，而不是巨大的二进制差异。
• 透明使用： 对于开发者来说，工作流程（add, commit, push, pull, checkout）基本保持不变。
• 支持大文件： 专为管理 GB 级别的大文件而设计。

典型使用场景：

• 游戏开发（纹理、3D 模型、音频、视频）
• 多媒体项目（高清图片、视频、音频素材）
• 数据科学/机器学习（大型数据集、训练好的模型）
• 设计文档（PSD, AI, Sketch 文件）
• 发行包/安装程序（.exe, .dmg, .apk 等）
• 虚拟机镜像、容器镜像（如果必须放 Git 里）

---

Git LFS 使用示例 (以 GitHub 为例)

1. 安装 Git LFS

• macOS (Homebrew): brew install git-lfs
• Windows: 从 https://git-lfs.com/ 下载安装程序安装。
• Linux (Debian/Ubuntu): sudo apt-get install git-lfs
• 安装后初始化 LFS (全局一次):

  git lfs install
  # 这会设置必要的 Git 钩子 (hooks)，使 LFS 在仓库中生效。
  

2. 在新仓库中启用并配置 LFS

# 创建一个新目录并初始化 Git 仓库
mkdir my-lfs-project
cd my-lfs-project
git init

# 告诉 Git LFS 跟踪特定类型的文件（例如所有 .psd 文件 和 所有超过 100MB 的文件）
git lfs track "*.psd"          # 跟踪所有 .psd 文件
git lfs track "*.zip"          # 跟踪所有 .zip 文件
git lfs track "*.mp4"          # 跟踪所有 .mp4 文件
git lfs track --size=100M "*"  # 跟踪所有超过 100MB 的文件（谨慎使用，确保只跟踪必要的大文件）

# 查看当前跟踪模式 (会列出 .gitattributes 中的规则)
git lfs track

# 将生成的 .gitattributes 文件添加到 Git 仓库中（非常重要！）
git add .gitattributes
git commit -m "Add .gitattributes to track large files with LFS"

3. 添加、提交和推送大文件

# 将一个大文件 (e.g., huge_video.mp4) 放入项目目录
cp ~/Videos/huge_video.mp4 .

# 像添加普通文件一样添加它。Git LFS 会自动拦截！
git add huge_video.mp4

# 提交更改
git commit -m "Add large video asset"

# 添加远程仓库 (假设在 GitHub 上创建了一个名为 my-lfs-project 的空仓库)
git remote add origin https://github.com/your-username/my-lfs-project.git

# 推送更改（包括提交历史和 LFS 文件）
git push -u origin main
# 在推送过程中，你会看到类似下面的输出，表明 LFS 文件正在上传：
# Uploading LFS objects: 100% (1/1), 512 MB | 10 MB/s, done.

4. 克隆包含 LFS 文件的仓库

# 克隆仓库（需要已经安装了 git-lfs）
git clone https://github.com/your-username/my-lfs-project.git
cd my-lfs-project

# 在克隆过程中，或者首次检出包含 LFS 指针的分支（如 main）时，Git LFS 会自动下载所需的大文件：
# 输出示例：
# Filtering content: 100% (1/1), 512.00 MiB | 5.21 MiB/s, done.

5. 拉取更新（包含新的 LFS 文件）

git pull origin main
# 如果拉取的提交引入了新的 LFS 文件，它们也会被自动下载。

6. 其他常用命令

• 检查文件状态： 查看哪些文件被 LFS 管理，以及它们的状态。

  git lfs status
  

• 列出跟踪的文件模式：

  git lfs track
  

• 停止跟踪文件模式：

  git lfs untrack "*.tiff"
  git add .gitattributes # 记得提交 .gitattributes 的更改
  

• 迁移历史中的大文件到 LFS (高级)： 如果仓库历史中已经存在大文件，可以使用 git lfs migrate 将其迁移到 LFS。操作需谨慎，会重写历史！ 务必先备份仓库。

  # 示例：将历史中所有超过 10MB 的 .zip 文件迁移到 LFS
  git lfs migrate import --include="*.zip" --above="10MB"
  # 然后需要强制推送 (git push --force)，并告知所有协作者重新克隆。
  

• 查看 LFS 文件详情：

  git lfs ls-files # 显示当前检出分支中被 LFS 跟踪的文件列表及其状态
  

重要注意事项：

1. .gitattributes 文件是关键： 必须将这个文件提交到仓库中。它定义了哪些文件应该用 LFS 管理。没有它，LFS 跟踪规则不会生效。
2. LFS 存储配额： GitHub、GitLab、Bitbucket 等提供的免费 LFS 存储通常有限额（例如 GitHub Free 是 1GB 带宽/月，存储通常 1-2GB）。超出需要付费或自建 LFS 服务器。
3. 访问权限： 克隆包含 LFS 文件的私有仓库时，用户除了需要 Git 的访问权限，还需要有权限访问对应的 LFS 存储服务器（通常托管服务商已集成好）。
4. 自建 LFS 服务器： 可以使用开源的 LFS 服务器实现（如 lfs-test-server, Artifactory, Nexus Repository Manager）替代托管服务商的存储。
5. .gitignore vs .gitattributes： .gitignore 告诉 Git 完全忽略某些文件。.gitattributes 告诉 Git 如何处理特定文件（比如用 LFS 管理、指定 diff 方式等）。
6. 误传大文件： 如果不小心用普通 Git add 了一个非常大的文件（未经过 LFS），并且 push 到了远程，会导致仓库膨胀。补救方法是：
   • 使用 git rm --cached 移除错误添加的大文件。
   • 使用 git commit --amend 或 git rebase 移除包含大文件的提交（重写历史）。
   • 强制推送 (git push --force)。
   • 联系托管服务商管理员，他们可能能清理远端缓存（但通常很麻烦）。
   • 最好的办法是提前正确配置好 .gitattributes 和 LFS！

总结： Git LFS 是管理 Git 仓库中大文件的必备工具。它通过用轻量级指针替换实际大文件内容，保持 Git 仓库的精简和高效，同时提供近乎透明的用户体验。只需记住安装 LFS 客户端、正确配置 .gitattributes 并提交该文件，之后的操作流程与普通 Git 基本一致。