介绍

Git 是为文本文件而不是大型二进制文件设计的。当大文件进入 Git 存储库时，克隆时间会增加，存储库大小会膨胀，并且 git log 等操作会变慢。 Git LFS（大文件存储）通过用存储库中的文本指针文件替换大文件，同时将实际内容存储在远程服务器上来解决这个问题。

指针文件是一个小文本文件，映射到 LFS 服务器上的内容：

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

现实世界的影响：设计团队的存储库在迁移到 LFS 后从 12GB 增加到 140MB。 Git LFS 现在是 Git 中大文件的标准解决方案，受到 GitHub、GitLab、Bitbucket 和自托管解决方案的支持。

1.LFS架构及安装

Git LFS 通过 smudge/clean 过滤器 工作。当您签出分支时，污迹过滤器会将指针文件替换为来自 LFS 服务器的实际内容。当您提交时，干净的过滤器会用指针替换大文件。

# Install Git LFS
git lfs install

# Verify installation
git lfs version

运行 git lfs install 会将条目添加到 .gitconfig 中，以在 filter.lfs 下配置涂抹和清洁过滤器。新的基于 SSH 的协议使用 git-lfs-transfer 命令进行身份验证传输，而不依赖于 HTTPS。

安装因平台而异：

• Windows：git lfs install（包含在 Windows 版 Git 中）
• macOS：brew install git-lfs && git lfs install
• Linux：apt install git-lfs (Debian/Ubuntu) 或 yum install git-lfs (RHEL/Fedora)

2. 跟踪模式和配置

使用 git lfs track 配置 LFS 以跟踪特定文件模式。这会将条目添加到您的 .gitattributes 文件中，该文件必须提交给团队范围内采用。

# Track common binary file types
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.tar.gz"
git lfs track "*.h5"
git lfs track "*.onnx"

生成的 .gitattributes 条目如下所示：

*.psd filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text
*.h5 filter=lfs diff=lfs merge=lfs -text

您还可以将模式范围限定到特定目录或使用否定模式：

assets/**/*.png filter=lfs diff=lfs merge=lfs -text
!assets/thumbnails/*.png

使用 git lfs track 查看所有跟踪的模式并直接检查 .gitattributes 文件。请记住：必须为团队的其他成员提交模式才能继承它们。

3. 文件大小限制和带宽管理

LFS 存储和带宽由托管提供商计量：

要估算成本，请根据当前跟踪的文件计算总 LFS 存储，并根据团队规模和文件更新频率计算每月带宽。降低成本的策略包括：

# Prune old LFS revisions from local cache
git lfs prune

# Enable deduplication for storage efficiency
git lfs dedup

# Limit what is fetched on clone via .lfsconfig
[lfs]
  fetchinclude = "assets/**"
  fetchexclude = "archive/**"

使用 lfs.<url>.access 进行后台身份验证配置。对于多个文件，默认的批量传输模式比顺序模式更有效。

4. 从常规 Git 跟踪迁移

对于已提交大文件的现有存储库，请使用 git lfs migrate 重写历史记录并用 LFS 指针替换大文件。

# Backup first — this rewrites history
git lfs migrate import --include="*.psd,*.zip" --everything

迁移过程：

1. 备份存储库
2. 使用适当的 --include 模式运行 git lfs migrate import
3. 使用 git lfs ls-files --all 进行验证
4. 与团队协调，然后强力推动
5. 每个人都重新克隆

# Verify migrated files
git lfs ls-files --all

# Force push (coordinate with team first)
git push --force --all

重要：重写历史记录会更改提交哈希值，需要强制推送，并中断打开的拉取请求。对于破坏性较小的方法，仅使用 git lfs track 开始跟踪未来的文件 - 这可以避免历史重写，但代价是将过去的大文件留在历史记录中。

案例研究：将历史 .psd、.fbx 和 .unitypackage 文件迁移到 LFS 后，5GB Unity 游戏存储库减少到 280MB。

5. CI/CD 集成

将 LFS 与 CI/CD 管道集成需要显式配置。

GitHub Actions：在 actions/checkout@v4 中使用 lfs: true 选项，或在签出后手动运行 git lfs pull。

- uses: actions/checkout@v4
  with:
    lfs: true

GitLab CI：设置 GIT_LFS_SKIP_SMUDGE 以在不需要时禁用 LFS，并有选择地运行 git lfs pull。

variables:
  GIT_LFS_SKIP_SMUDGE: "1"

before_script:
  - apt-get update && apt-get install -y git-lfs
  - git lfs install
  - git lfs pull --include="models/**"

通过以下方式优化 CI：

• 对于不需要大文件的作业，跳过 LFS 拉取
• 使用 --include/--exclude 只获取需要的内容
• 在 CI 运行之间缓存 .git/lfs 目录
• 在 LFS 服务器附近使用自托管运行器以降低带宽成本

6. 存储库清理和维护

通过定期维护命令保持 LFS 存储库的健康。

# Remove old LFS revisions from local storage
git lfs prune --recent --verify-remote

# List all tracked LFS files
git lfs ls-files --all

# Find the largest files
git lfs migrate info --everything --top=10

通过 GitHub 的存储设置或其他平台上的等效控件清理远程上的孤立 LFS 对象。跨分支仔细管理 .gitattributes — LFS 模式中的合并冲突由 LFS 合并驱动程序解决，该驱动程序选择一个版本。使用 lfs.allowincompletepush 优雅地处理中断的推送。

7. 替代方案比较

Git LFS 并不总是正确的选择。考虑以下替代方案：

• DVC（数据版本控制）：专为具有数据集版本控制、管道跟踪和云存储后端的 ML 工作流程而设计。对于 ML 来说比 LFS 更好，但对于简单的二进制管理来说更复杂。
• Git Annex：支持灵活的存储后端、部分文件访问和加密。更强大但也更复杂。
• Perforce：对于游戏开发中非常大的二进制资产（100GB+），Perforce 的集中式模型可以优于 Git LFS。

8. 故障排除和常见问题

结论

Git LFS 是 Git 中大文件的事实上的标准。关键要点：尽早跟踪模式，通过团队协调仔细迁移，监控存储和带宽配额，通过选择性获取优化 CI，并使用 git lfs prune 定期清理。在项目设置初期制定 LFS 指南，而不是稍后进行改造。对于特定于 ML 的工作流程，评估 DVC；对于海量二进制资产，请考虑 Perforce 或 Git Annex。