山花落尽，我心犹青

第一步：下载并安装Git LFS#

访问Git LFS官方网站：https://git-lfs.com

根据你的操作系统选择对应的安装方式：

Windows用户：

• 下载安装程序直接运行
• 或使用包管理器：choco install git-lfs

macOS用户：

1
brew install git-lfs

Linux用户（Ubuntu/Debian）：

1
sudo apt install git-lfs

安装完成后，在终端验证是否成功：

1
git lfs --version

如果看到类似 git-lfs/3.4.0 (GitHub; linux amd64) 的输出，说明安装成功。

第二步：初始化Git LFS#

打开你的本地克隆仓库，在终端中进入仓库目录，然后运行：

1
git lfs install

这个命令会在你的git全局配置中添加LFS相关的设置。只需要执行一次，之后所有仓库都可以使用LFS功能。

TIP

git lfs install 是全局配置，如果你只想在当前仓库启用LFS，可以使用 git lfs install --local。

第三步：指定需要跟踪的大文件类型#

这是最关键的一步。你需要告诉Git LFS哪些文件应该被它管理。使用以下命令：

1
git lfs track "*.zip"

这里的 *.zip 是一个通配符模式，表示所有以 .zip 结尾的文件都会被LFS接管。你可以根据需要替换成其他扩展名，比如：

• "*.zip" - 压缩包
• "*.pkl" - Python pickle模型文件
• "*.h5" - HDF5模型文件
• "*.tar.gz" - 压缩包
• "*.mp4" - 视频文件
• "*.psd" - Photoshop设计文件

你还可以同时跟踪多种类型：

1
git lfs track "*.zip" "*.pkl" "*.mp4"

执行这个命令后，git会自动创建一个 .gitattributes 文件（如果不存在的话），并添加相应的配置。你可以查看这个文件的内容：

1
cat .gitattributes

输出应该类似：

1
*.zip filter=lfs diff=lfs merge=lfs -text
2
*.pkl filter=lfs diff=lfs merge=lfs -text

第四步：将文件添加到暂存区#

现在，你可以像平常一样将文件添加到git暂存区：

1
git add .

或者指定具体的文件：

1
git add your_large_file.zip
2
git add .gitattributes

第五步：提交并推送到GitHub#

提交你的更改：

1
git commit -m "添加大文件，使用Git LFS管理"

然后推送到远程仓库：

1
git push origin main

如果一切顺利，你应该能看到类似这样的输出：

1
Uploading LFS objects: 100% (1/1), 152 MB | 5.2 MB/s, done.
2
Enumerating objects: 5, done.
3
...
4
To https://github.com/yourusername/yourrepo.git
5
   abc1234..def5678  main -> main

错误1：先add了大文件，后配置LFS#

这是最容易踩的坑。如果你像作者一样，先把大文件add到暂存区，发现上传不了，最后才去配置LFS，那么git仍然会把这个大文件当作普通文件来上传，导致推送失败。

原因：git在 git add 时已经决定如何存储这个文件。即使你后续配置了LFS，已经add过的文件不会自动切换到LFS管理。

解决方法：

1. 取消暂存大文件：

   1
   git reset HEAD your_large_file.zip
   

2. 配置LFS（如果还没配置）：

   1
   git lfs track "*.zip"
   

3. 重新添加文件：

   1
   git add your_large_file.zip
   

4. 提交并推送：

   1
   git commit -m "使用LFS管理大文件"
   2
   git push origin main
   

错误2：已经push了包含大文件的commit#

如果你已经不小心提交了大文件（即使推送失败），这些大文件仍然存在于你的git历史中。你需要清理历史记录：

方法一：使用BFG Repo-Cleaner（推荐）

1
# 下载BFG工具
2
java -jar bfg.jar --delete-files your_large_file.zip
3

4
# 清理并强制推送
5
git reflog expire --expire=now --all && git gc --prune=now --aggressive
6
git push origin main --force

方法二：使用git filter-branch

1
git filter-branch --force --index-filter \
2
  "git rm --cached --ignore-unmatch your_large_file.zip" \
3
  --prune-empty --tag-name-filter cat -- --all

WARNING

强制推送会覆盖远程仓库的历史，如果仓库有协作者，请务必提前沟通。

错误3：克隆仓库时大文件没有下载#

当你克隆一个使用LFS的仓库时，默认只会下载指针文件。要获取真正的文件内容，需要运行：

1
git lfs pull

或者在克隆时直接下载：

1
git clone https://github.com/yourusername/yourrepo.git
2
cd yourrepo
3
git lfs pull

也可以使用 GIT_LFS_SKIP_SMUDGE 环境变量来控制：

1
# 克隆时跳过LFS文件下载（只获取指针）
2
GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/yourusername/yourrepo.git
3

4
# 之后按需下载
5
cd yourrepo
6
git lfs pull --include="*.zip"