Help us learn about your current experience with the documentation. Take the survey.

Git Large File Storage (LFS)

Git Large File Storage (LFS) 是一个开源的 Git 扩展，帮助 Git 仓库高效管理大型二进制文件。Git 无法像跟踪文本文件变更那样跟踪二进制文件（如音频、视频或图像文件）的变更。虽然基于文本的文件可以生成纯文本差异，但对二进制文件的任何变更都需要 Git 在仓库中完全替换该文件。对大文件的重复变更会增加你的仓库体积。随着时间的推移，这种体积增长可能会减慢 clone、fetch 或 pull 等常规 Git 操作的速度。

使用 Git LFS 将大型二进制文件存储在你的 Git 仓库之外，只留下一个小的文本指针供 Git 管理。当你使用 Git LFS 向仓库添加文件时，GitLab 会：

  1. 将文件添加到你的项目配置的对象存储中，而不是 Git 仓库中。

  2. 在 Git 仓库中添加一个指向大文件的指针，而不是大文件本身。该指针包含你的文件信息，如下所示：

    version https://git-lfs.github.com/spec/v1
oid sha256:lpca0iva5kpz9wva5rgsqsicxrxrkbjr0bh4sy6rz08g2c4tyc441rto5j5bctit
size 804
    • Version - 使用的 Git LFS 规范版本
    • OID - 使用的哈希方法，以及唯一对象 ID，格式为 {hash-method}:{hash}。
    • Size - 文件大小，以字节为单位。

  3. 排队作业以重新计算你的项目统计信息，包括存储大小和 LFS 对象存储。你的 LFS 对象存储是与你的仓库关联的所有 LFS 对象大小的总和。

使用 Git LFS 管理的文件在文件名旁边显示一个 LFS 标识：

Git LFS 跟踪状态

Git LFS 客户端使用 HTTP Basic 认证，并通过 HTTPS 与你的服务器通信。在你验证请求后，Git LFS 客户端会收到关于从何处获取（或推送）大文件的说明。

你的 Git 仓库保持较小的体积，这有助于你遵守仓库大小限制。有关更多信息，请参阅 GitLab 自托管版 和 GitLab SaaS 的仓库大小限制。

了解 Git LFS 如何与 fork 协作

当你 fork 一个仓库时，你的 fork 包含了你在 fork 时刻上游仓库中已有的 LFS 对象。如果你向你的 fork 添加新的 LFS 对象，它们只属于你的 fork，而不属于上游仓库。总对象存储量仅对你的 fork 增加。

当你从你的 fork 创建合并请求返回到上游项目，并且你的合并请求包含新的 Git LFS 对象时，GitLab 在合并后将新的 LFS 对象与上游项目关联。

为项目配置 Git LFS

  • 层级：Free、Premium、Ultimate
  • 提供方式：GitLab Self-Managed、GitLab Dedicated

GitLab 默认为 GitLab Self-Managed 和 GitLab SaaS 启用 Git LFS。它提供服务器级设置和项目级设置。

  • 要在你的实例上配置 Git LFS，例如设置远程对象存储，请参阅 GitLab Git Large File Storage (LFS) 管理。

  • 要为特定项目配置 Git LFS：

    1. 在你本地仓库的根目录中，运行 git lfs install。此命令会添加：
      • 一个预推送 Git 钩子到你的仓库。
      • 一个 .gitattributes 文件 来跟踪单个文件和文件类型的处理方式。
    2. 添加你想要用 Git LFS 跟踪的文件和文件类型。

启用或禁用项目的 Git LFS

Git LFS 默认为 GitLab Self-Managed 和 GitLab SaaS 启用。

先决条件：

  • 你必须拥有项目的至少 Developer 角色。

要启用或禁用项目的 Git LFS：

  1. 在左侧边栏，选择 搜索或转到 并找到你的项目。
  2. 选择 设置 > 常规。
  3. 展开 可见性、项目功能、权限 部分。
  4. 选择 Git Large File Storage (LFS) 开关。
  5. 选择 保存更改。

添加和跟踪文件

你可以将大文件添加到 Git LFS。这有助于你在 Git 仓库中管理文件。当你使用 Git LFS 跟踪文件时，它们在 Git 中会被文本指针替换，并存储在远程服务器上。有关更多信息，请参阅 Git LFS。

当你为项目配置 Git LFS 时，确保你的项目根目录中有 .gitattributes 文件。如果没有根级别的 .gitattributes 文件，即使你在项目子目录中正确配置了 LFS，UI 也会显示警告。有关更多信息，请参阅 LFS 配置警告消息。

克隆使用 Git LFS 的仓库

当你克隆使用 Git LFS 的仓库时，Git 会检测到 LFS 跟踪的文件并通过 HTTPS 克隆它们。如果你使用 SSH URL 运行 git clone，例如 [email protected]:group/project.git，你必须再次输入你的 GitLab 凭据以进行 HTTPS 认证。

默认情况下，Git LFS 操作通过 HTTPS 进行，即使 Git 通过 SSH 与你的仓库通信。在 GitLab 17.2 中，引入了 LFS 的纯 SSH 支持。有关如何启用此功能的信息，请参阅 纯 SSH 传输协议。

要为你已克隆的仓库获取新的 LFS 对象，请运行以下命令：

git lfs fetch origin main

将现有仓库迁移到 Git LFS

阅读 git-lfs-migrate 文档 了解如何使用 Git LFS 迁移现有的 Git 仓库。

从仓库历史中删除 Git LFS 文件

理解在 Git LFS 中取消跟踪文件和删除文件之间的区别很重要：

  • 取消跟踪：文件仍然在磁盘上和你的仓库历史中。如果用户检出历史分支或标签，他们仍然需要该文件的 LFS 版本。
  • 删除：文件被删除，但仍保留在你的仓库历史中。

要删除使用 Git LFS 跟踪的文件，请参阅 删除文件。

要完全清除文件的所有历史记录（过去和现在），请参阅 处理敏感信息。

清除文件历史记录需要重写 Git 历史。此操作具有破坏性且不可逆。

删除大文件后减少仓库大小

如果需要从仓库历史中删除大文件以减少仓库的总大小，请参阅 减少仓库大小。

相关主题