解决 Git 大文件问题：安装 Git LFS 指南 – wiki基地

作者： /

解决 Git 大文件问题：安装 Git LFS 详细指南

在现代软件开发和协作中，Git 已经成为版本控制的事实标准。它以其分布式、高效的分支管理和快速的操作而闻名。然而，Git 的设计初衷是为源代码这种文本文件而优化的。对于大型二进制文件，如图像、视频、音频、数据集、编译好的程序、虚拟机镜像等，Git 的表现可能会变得非常糟糕，甚至无法使用。

想象一下，你的项目仓库里包含一个几百兆甚至几个 G 的素材文件。当你第一次克隆这个仓库时，可能需要漫长的等待。更糟糕的是，如果你在项目的历史中修改了这个大文件几次，每次修改都会被 Git 完整地记录下来。这意味着你的 .git 目录（存储所有历史数据的地方）会迅速膨胀，变得非常庞大。

当仓库体积庞大时，许多日常 Git 操作都会变得缓慢：
* 克隆 (Clone): 下载整个庞大的历史记录，耗时且占用带宽。
* 拉取 (Pull/Fetch): 同步远端改动时，需要处理大量数据。
* 分支切换 (Checkout): Git 需要根据历史记录重构工作区，如果某个分支的历史包含大量大文件，切换会非常慢。
* 打包 (Packing): Git 会定期对对象进行打包以节省空间，但对于无法有效压缩的大文件，这效果甚微，打包过程本身可能耗尽资源。
* 垃圾回收 (Garbage Collection): 清理不再需要的对象，但如果历史中充斥着大文件的不同版本，清理效率低下。

更严重的是，一旦大文件进入了 Git 的历史记录，即使你后来删除了它，它仍然存在于仓库的 .git 目录中，除非你重写历史（rebase 或 filter-branch），而重写历史是一个复杂且有风险的操作，尤其是在多人协作的环境中。

Git LFS (Large File Storage)：优雅的解决方案

为了解决 Git 在处理大文件时的弊端，Git Large File Storage（简称 Git LFS）应运而生。Git LFS 是一个开源的 Git 扩展，它改变了 Git 处理大文件的方式，使其对开发者更加友好和高效。

Git LFS 的核心思想是：不将大文件直接存储在 Git 仓库中，而是将它们替换为小的文本指针文件，并将实际的大文件内容存储在另外一个专门的服务器上（通常是 Git 托管服务提供商，如 GitHub、GitLab、Bitbucket 提供的 LFS 服务，或自建 LFS 服务器）。

它是如何工作的？

  1. 追踪 (Tracking): 你告诉 Git LFS 哪些类型的文件应该被它管理（例如所有的 .psd 文件，所有的 .mp4 文件等），这通过配置 .gitattributes 文件来实现。
  2. 提交 (Commit): 当你提交一个被 Git LFS 追踪的大文件时，Git LFS 会拦截这个操作。它会计算大文件的 SHA-256 哈希值、文件大小等信息，创建一个小的文本文件（称为“指针文件”），然后将指针文件交给 Git 进行版本控制。原始的大文件则被移到一个本地的 Git LFS 缓存区。
  3. 指针文件 (Pointer File): 这个指针文件非常小，通常只有几十个字节，内容包含 LFS 对象的版本、大文件的 SHA-256 哈希值以及文件大小。例如：
    version https://git-lfs.github.com/spec/v1
    oid sha256:f7802499f...
    size 123456789
    Git 仓库（包括历史记录）现在只存储这些小的指针文件。
  4. 推送 (Push): 当你执行 git push 命令时，Git LFS 也会拦截这个操作。在 Git 推送提交和指针文件的同时，Git LFS 会检查本地 LFS 缓存区，发现有新的大文件（对应的指针文件被推送了），它会将这些新的大文件内容上传到远端的 LFS 服务器。
  5. 克隆/拉取/切换 (Clone/Pull/Checkout): 当你克隆或拉取一个包含 LFS 指针文件的仓库，或者切换到一个包含 LFS 指针文件的分支时，Git 会先拉取到指针文件。然后，Git LFS 会根据指针文件中的信息（哈希值），从远端的 LFS 服务器下载对应的大文件内容，并将其放置在你的工作目录中正确的位置。这个过程对用户是透明的，感觉就像 Git 自己在处理文件一样。

Git LFS 的优点：

  • 减小 Git 仓库体积： Git 仓库本身只存储小的指针文件，历史记录保持精简。
  • 加速基本 Git 操作： 克隆、拉取、分支切换等操作因为不再需要下载和处理大量大文件历史而变得更快。
  • 更友好的协作： 不会因为某人提交了大文件而导致整个团队的仓库变得臃肿难用。
  • 利用优化的存储： LFS 服务器通常针对大文件存储进行优化，比 Git 本身的文件存储效率更高。

Git LFS 的缺点（或需要注意的地方）：

  • 额外的存储需求： LFS 文件存储在 Git 托管服务提供的 LFS 存储空间中，这通常有免费额度限制，超出部分可能需要额外付费。
  • 依赖 LFS 服务器： 要完整获取大文件内容，需要能够访问 LFS 服务器。如果服务器不可用或你没有权限，你只能看到指针文件而无法获取实际内容。
  • 客户端支持： 所有参与协作的开发者都需要安装并启用 Git LFS 才能正常工作。

安装 Git LFS

安装 Git LFS 是使用它的第一步，也是一个相对简单的过程。Git LFS 支持多种操作系统，可以通过不同的方式进行安装。

第一步：检查是否已安装

在开始安装之前，最好先检查一下你的系统中是否已经安装了 Git LFS。打开终端或命令行工具，输入以下命令：

bash
git lfs version

如果 Git LFS 已经安装并且在系统的 PATH 环境变量中，你会看到类似以下的输出，显示 Git LFS 的版本号：

git-lfs/3.4.0 (GitHub; linux amd64; go 1.21.4)

如果你看到错误提示，例如 command not found 或 git: 'lfs' is not a git command，说明你需要安装 Git LFS。

第二步：选择适合你的操作系统的安装方法

Git LFS 提供了多种安装方式，你可以选择最适合你的操作系统和习惯的方式。

方法 1：使用包管理器 (推荐)

对于大多数 Linux 和 macOS 用户，使用系统自带的包管理器是安装 Git LFS 最简单和推荐的方式。

  • 在 Debian/Ubuntu 或其衍生版 Linux 上 (使用 apt):

    打开终端，运行以下命令：

    bash
    sudo apt-get update
    sudo apt-get install git-lfs

    sudo apt-get update 用于更新你的本地包列表，确保你能够获取到最新版本的软件包信息。sudo apt-get install git-lfs 则会下载并安装 Git LFS 及其依赖项。安装过程可能需要你输入管理员密码。

  • 在 Fedora/CentOS/RHEL 或其衍生版 Linux 上 (使用 yum 或 dnf):

    对于较旧的系统使用 yum：

    bash
    sudo yum install git-lfs

    对于较新的系统使用 dnf：

    bash
    sudo dnf install git-lfs

    同样，你需要管理员权限来执行安装。

  • 在 macOS 上 (使用 Homebrew):

    Homebrew 是 macOS 上非常流行的包管理器。如果你还没有安装 Homebrew，可以访问 https://brew.sh/ 按照官方指南进行安装。安装 Homebrew 后，打开终端，运行：

    bash
    brew install git-lfs

    Homebrew 会自动下载、编译（如果需要）并安装 Git LFS。

  • 在 Windows 上 (使用 Chocolatey):

    Chocolatey 是 Windows 上的一个包管理器，类似于 Linux 的 apt 或 macOS 的 Homebrew。如果你还没有安装 Chocolatey，可以访问 https://chocolatey.org/install 按照官方指南进行安装。安装 Chocolatey 后，以管理员身份打开命令提示符或 PowerShell，运行：

    powershell
    choco install git-lfs

    Chocolatey 会负责下载并安装 Git LFS。

方法 2：使用官方安装程序

Git LFS 官方提供了针对 Windows 和 macOS 的安装程序。这是一种无需额外包管理器即可安装的简单方式。

  • 访问 Git LFS 官方 GitHub Release 页面：
    前往 https://github.com/git-lfs/git-lfs/releases

  • 下载适合你操作系统的安装包：
    在 Releases 页面找到最新版本（通常是顶部），展开 “Assets” 部分。

    • 对于 Windows，下载 .exe 文件 (例如 git-lfs-windows-amd64-vX.Y.Z.exe)。
    • 对于 macOS，下载 .pkg 文件 (例如 git-lfs-darwin-amd64-vX.Y.Z.pkg)。

  • 运行安装程序：
    下载完成后，像安装普通软件一样运行下载的安装文件，按照向导提示完成安装。安装程序通常会自动将 Git LFS 添加到系统的 PATH 环境变量中。

方法 3：从源代码构建 (高级)

如果你是开发者或有特定需求，也可以选择从 Git LFS 的源代码进行构建安装。这需要你的系统上安装 Go 语言环境。

  • 安装 Go 语言环境： 访问 https://go.dev/doc/install 根据你的操作系统安装 Go。
  • 获取 Git LFS 源代码：
    bash
    git clone https://github.com/git-lfs/git-lfs.git
    cd git-lfs
  • 构建和安装：
    bash
    make
    sudo make install # 可能需要管理员权限，取决于你的安装位置
    make 命令会编译源代码生成可执行文件，make install 会将可执行文件复制到系统 PATH 中的一个目录（例如 /usr/local/bin）。

第三步：完成 Git LFS 的全局设置

安装 Git LFS 可执行文件后，你还需要在 Git 中启用 LFS 过滤器。这一步只需要执行一次（通常推荐设置为全局），Git LFS 就会将必要的钩子（hooks）安装到你的 Git 环境中，以便在 clone, fetch, pull, push 等操作时拦截并调用 Git LFS。

打开终端或命令行，运行以下命令：

bash
git lfs install

运行这个命令后，你会看到类似的输出：

Updated global Git hooks.
Git LFS initialized.

  • 全局安装 (默认): 如果你直接运行 git lfs install，它会修改你的全局 Git 配置（~/.gitconfig 或 C:\Users\YourUser\.gitconfig），添加必要的过滤器和钩子配置。这意味着任何新的或现有的仓库，只要配置了 LFS 跟踪规则 (.gitattributes)，Git LFS 就会自动介入工作。这是最常见的用法。
  • 系统级别安装: 你可以使用 git lfs install --system 来修改系统的 Git 配置。这通常用于多用户系统，为所有用户启用 LFS。
  • 本地仓库安装: 如果只想在 当前 仓库启用 Git LFS，可以使用 git lfs install --local。这会修改当前仓库的配置（.git/config）。通常不推荐这种方式，除非你有特殊需求，因为它意味着每个使用这个仓库的人都需要在本地执行一次 git lfs install --local。

推荐的方式是在安装后执行一次 git lfs install 进行全局设置。 这样，当你在任何配置了 .gitattributes 文件来跟踪 LFS 文件的仓库中工作时，Git LFS 都会自动生效。

第四步：验证安装

再次运行 git lfs version 命令，确认 Git LFS 可执行文件已经安装并可以访问。

然后，你可以进入任何一个 Git 仓库（或者新建一个测试仓库），运行 git lfs install (如果之前不是全局安装的话，或者想确保本地仓库也配置了LFS) 和 git lfs env 命令来查看 Git LFS 的环境信息，确认它已经被正确集成到 Git 中。

bash
cd your_repo # 进入你的 Git 仓库
git lfs install # 可选，确保当前仓库配置了LFS
git lfs env

git lfs env 命令会输出非常详细的环境信息，包括 Git 版本、Git LFS 版本、操作系统信息、local, system, global 级别的 Git 配置中关于 LFS 的设置、远程仓库信息以及 LFS 缓存目录的位置等。通过检查这些输出，你可以确认 Git LFS 是否已经被正确地安装和配置。

基本使用 Git LFS

安装并设置好 Git LFS 后，你就可以开始在你的仓库中使用它来管理大文件了。

1. 初始化仓库 (如果尚未是 Git 仓库):

如果你正在处理一个全新的项目：

bash
git init

如果你在一个现有的项目中使用 LFS：

“`bash

确保你在项目根目录

“`

2. 在仓库中启用 Git LFS:

虽然你可能已经做了全局安装 (git lfs install 没有 --local 或 --system 参数)，但通常推荐在每个需要使用 LFS 的仓库中也运行一次 git lfs install。这会确保仓库级别的配置是正确的，并且在克隆仓库时，LFS 钩子也会被自动设置（如果克隆时就启用了 LFS）。

bash
git lfs install

这个命令会在 .git/config 文件中添加一些 LFS 相关的配置，并安装必要的 Git 钩子到 .git/hooks 目录。如果你的全局已经设置好了，这一步更多是确保仓库本身具备 LFS 工作所需的环境。

3. 告诉 Git LFS 追踪哪些文件类型:

这是使用 Git LFS 的关键步骤。你需要指定哪些文件应该被 LFS 管理，而不是直接存储在 Git 中。这通过 git lfs track 命令来实现，它会在仓库的根目录生成或修改 .gitattributes 文件。

例如，要追踪所有扩展名为 .psd 的文件和位于 assets/videos 目录下的所有 .mp4 文件：

bash
git lfs track "*.psd"
git lfs track "assets/videos/*.mp4"

你可以追踪单个文件、使用通配符 (*) 匹配多种文件或匹配目录下的文件。

git lfs track 命令做了两件事：
* 它会打印出 .gitattributes 文件中新增或修改的行。例如，运行 git lfs track "*.psd" 会在 .gitattributes 中添加一行 *.psd filter=lfs diff=lfs merge=lfs -text。
* 它会自动将 .gitattributes 文件添加到 Git 的暂存区，提示你将其提交。

检查正在被 Git LFS 追踪的文件类型:

你可以使用 git lfs track 命令不带参数来查看当前仓库中哪些模式正在被 Git LFS 追踪：

bash
git lfs track

输出会列出 .gitattributes 文件中所有被 LFS 追踪的模式。

4. 添加 .gitattributes 文件并提交:

.gitattributes 文件是 Git LFS 配置的核心，它必须被版本控制，以便团队成员知道哪些文件应该被 LFS 管理。

bash
git add .gitattributes
git commit -m "Configure Git LFS to track large files"

5. 添加并提交要被 LFS 管理的大文件:

现在，你可以像平常一样添加和提交你的大文件了。Git LFS 会在后台自动处理。

“`bash

假设你有一个大文件 your_large_image.psd 和一个视频文件 assets/videos/intro.mp4

git add your_large_image.psd assets/videos/intro.mp4
git commit -m “Add large image and intro video using Git LFS”
“`

当你执行 git add 时，Git LFS 的 clean 过滤器会介入，将大文件内容替换为指针文件，并将实际内容移动到 LFS 缓存。当你执行 git commit 时，Git 会将这些小的指针文件提交到仓库历史中。

验证文件是否被 LFS 管理:

你可以通过查看文件的内容来验证它是否被 LFS 管理。在工作目录中，文件的内容看起来是正常的（因为 Git LFS 在你 checkout 时会自动下载真实内容）。但是，在 Git 仓库内部（例如通过查看对象或者在提交后查看历史版本中的文件内容），你会看到那个小的指针文件。

“`bash

在工作目录，你会看到文件的实际内容

cat your_large_image.psd # (取决于文件类型，可能无法直接cat看到，但文件大小是正常的)

在 Git 内部，你可以查看提交中的文件内容 (这会显示指针文件)

git cat-file -p HEAD:your_large_image.psd # (这应该显示 LFS 指针内容)
“`

或者，更直观的方法是使用 git lfs status 命令：

bash
git lfs status

这个命令会显示哪些被追踪的文件已经被修改并准备提交，以及哪些文件尚未被追踪。

6. 推送改动到远端:

当你推送包含 LFS 指针文件的提交时，Git LFS 会在 Git 推送之前或之后（取决于配置和版本）将对应的 LFS 对象上传到远端 LFS 服务器。

bash
git push origin main # 或你的分支名

在推送过程中，你可能会看到 Git LFS 上传文件的进度信息，例如：

Uploading LFS objects: 100% (2/2), 120 MB | 1.5 MB/s, done

这表明 Git LFS 正在将实际的大文件内容上传到 LFS 服务器。

7. 克隆或拉取包含 LFS 文件的仓库:

当你克隆或拉取一个包含 Git LFS 文件的仓库时，Git LFS 会自动下载对应的 LFS 对象。

bash
git clone your_repo_url # 克隆时会自动下载 LFS 文件
git pull # 拉取时会自动下载新的 LFS 文件

如果你克隆了一个仓库，但 LFS 文件没有自动下载（可能是因为没有运行 git lfs install 或者遇到了网络问题），你可以手动拉取 LFS 对象：

bash
git lfs fetch
git lfs checkout

git lfs fetch 下载所有需要的 LFS 对象到本地缓存，git lfs checkout 根据当前的提交重写工作目录中的指针文件为实际文件。通常 git clone 和 git pull 会自动执行这些步骤。

迁移现有仓库中的大文件到 Git LFS

如果你有一个已经包含大量大文件的现有 Git 仓库，并且这些文件已经被提交到了历史记录中，那么仅仅安装 Git LFS 并追踪这些文件类型是不足够的。新的提交会使用 LFS，但历史记录中的大文件仍然会留在 .git 目录中，导致仓库依然臃肿。

要解决这个问题，你需要重写仓库的历史记录，将过去提交的大文件转换为 LFS 指针。这个过程通常使用 git lfs migrate 命令。

重要警告： 重写 Git 历史记录会改变现有提交的 SHA-1 哈希值。这会影响所有基于这些提交的分支和标签。在多人协作的环境中，重写历史后，其他团队成员需要强制拉取 (git pull --rebase 或 git pull --force) 或重新克隆仓库，这可能会导致数据丢失或工作中断。在执行迁移操作之前，务必备份你的仓库，并与团队成员充分沟通，确保所有人都了解并能正确处理后续的同步问题。

使用 git lfs migrate import 迁移：

这个命令可以遍历仓库的历史，找到符合指定模式的大文件，并将它们转换为 LFS 指针。

最常见的用法是迁移所有分支和标签中的特定类型文件：

bash
git lfs migrate import --everything --include="*.psd,*.zip,*.mp4"

  • --everything: 表示检查所有的分支和标签的历史记录。
  • --include="*.psd,*.zip,*.mp4": 指定要迁移的文件类型模式，多个模式用逗号分隔。

迁移步骤示例：

  1. 备份仓库： 这是最重要的步骤。复制整个仓库目录到其他地方。
    bash
    cp -R your_repo your_repo_backup
  2. 克隆一个干净的仓库副本 (可选但推荐): 在一个全新的克隆上执行迁移可以避免干扰你当前的工作分支。
    bash
    git clone your_repo_url your_repo_migration
    cd your_repo_migration
  3. 执行迁移命令：
    bash
    git lfs migrate import --everything --include="*.psd,*.zip,*.mp4" --verbose
    --verbose 参数可以让你看到迁移的详细过程。迁移过程可能需要一些时间，取决于仓库的大小和历史深度。
  4. 验证迁移结果：
    • 检查 .gitattributes 文件，确认 LFS 追踪规则已经被添加。
    • 查看仓库中原本的大文件，它们现在应该显示为 LFS 指针（通过 git cat-file -p <commit_hash>:<file_path> 查看历史版本的文件内容）。
    • 使用 git lfs ls-tree HEAD 或查看最新的提交，确认大文件已经是 LFS 指针。
    • 最重要的是，检查 .git 目录的大小。迁移成功后，清理旧对象 (git gc) 应该能显著减小 .git 目录的体积。
  5. 清理旧对象 (强制): 迁移完成后，旧的大文件对象仍然可能存在于 .git 目录中。你需要执行垃圾回收并指定一个截止日期来彻底清除这些旧对象。
    bash
    git reflog expire --expire=now --all
    git gc --prune=now
    警告： git gc --prune=now 会永久删除那些不再被任何引用（包括 reflog）指向的对象。确保你已经验证了迁移结果并且不需要回退到迁移前的状态。
  6. 强制推送 (谨慎操作): 由于历史已经被重写，你需要强制推送你的分支到远端仓库。
    bash
    git push --force --all # 推送所有分支
    git push --force --tags # 推送所有标签
    再次警告： 强制推送会覆盖远端仓库的历史。请确保你明白这样做的后果，并且已经与团队成员协调好。
  7. 通知团队成员： 告知所有协作者仓库历史已更改，他们需要重新克隆仓库，或者在现有本地仓库中进行特殊的拉取操作（例如先删除本地分支，再重新拉取远端分支）。最安全的方式通常是让他们备份当前工作，删除本地仓库，然后重新克隆。

迁移是一个涉及历史重写的高级操作，务必小心谨慎。对于复杂的迁移场景或需要更精细控制（例如只迁移特定提交范围内的文件），建议查阅 Git LFS 官方文档中关于 git lfs migrate 的详细说明。

常见问题与故障排除

  • LFS 文件没有被追踪： 确保你在仓库的根目录运行了 git lfs track 命令，并且将生成的 .gitattributes 文件添加并提交到了仓库中。使用 git lfs track 不带参数来检查当前的追踪模式。
  • 推送时 LFS 文件上传失败： 检查你的网络连接。确保你有权限上传到远端 LFS 服务器（通常与你的 Git 推送权限一致）。检查 Git 托管服务上的 LFS 存储空间是否已满或超出了免费额度。查看 Git LFS 的详细日志 (GIT_TRACE=1 GIT_CURL_VERBOSE=1 git push) 可以帮助诊断网络或权限问题。
  • 克隆/拉取后文件内容是 LFS 指针，而不是实际文件： 确保你已经正确安装并设置了 Git LFS (git lfs install)。这通常意味着 Git 的 smudge 过滤器没有正确工作。运行 git lfs env 检查配置。如果是在现有仓库拉取后出现问题，尝试手动运行 git lfs pull 或 git lfs fetch && git lfs checkout。
  • 仓库体积没有减小： 如果你迁移了历史中的大文件，必须执行 git gc --prune=now 等命令来清理旧的、悬空的大文件对象。请记住，git gc 只清理不再被任何引用指向的对象，所以确保你的 reflog 也被清理（git reflog expire --expire=now --all）。

结论

Git LFS 是解决 Git 在处理大文件时遇到的各种问题的强大工具。通过将大文件内容与 Git 仓库本身分离，它显著提高了包含大型资产的项目的版本控制效率和可用性。

安装 Git LFS 通常是一个简单快速的过程，通过包管理器或官方安装程序即可完成。安装后，只需一步全局设置 (git lfs install)，然后通过 git lfs track 命令在每个仓库中指定需要 LFS 管理的文件类型，就可以开始享受 Git LFS 带来的便利。

对于已经存在大文件历史的仓库，Git LFS 提供了 git lfs migrate 工具来帮助迁移，但这涉及历史重写，需要谨慎操作并充分沟通。

掌握 Git LFS 的安装和基本使用，是现代 Git 工作流程中处理大型二进制文件的必备技能，它能让你的 Git 仓库保持精简、操作流畅，让团队协作更加顺畅高效。

现在，按照本指南的步骤，安装并配置好 Git LFS，告别 Git 大文件带来的烦恼吧！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部