Featured image of post Git LFS：管理儲存庫中的大文件Featured image of post Git LFS：管理儲存庫中的大文件
Web

Git LFS：管理儲存庫中的大文件

用於大型檔案管理的 Git LFS 完整指南：設定、追蹤模式、檔案大小限制、頻寬成本、遷移、CI/CD 整合以及 DVC 等替代方案。

  1. 首頁
  2. Webs
  3. Git LFS：管理儲存庫中的大文件

介紹

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 儲存和頻寬由託管提供者計量：

供應商免費儲存免費頻寬/月
GitHub1 GB1 GB
GitLab因等級而異因等級而異
位元桶1.8 GB1.8 GB 1.8 GB

要估算成本，請根據當前追蹤的文件計算總 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 並不總是正確的選擇。考慮以下替代方案：

工具最適合儲存後端複雜性
Git LFS設計資產、二進位檔案原生 Git 託管低
DVCML 資料集、模型檔S3、GCS、SSH、SMB中
Git 附件大型媒體製作任何遠端（S3、Glacier 等）高
必然100GB+遊戲資源集中式伺服器高
  • DVC（資料版本控制）：專為具有資料集版本控制、管道追蹤和雲端儲存後端的 ML 工作流程而設計。對於 ML 來說比 LFS 更好，但對於簡單的二進位管理來說更複雜。
  • Git Annex：支援靈活的儲存後端、部分檔案存取和加密。更強大但也更複雜。
  • Perforce：對於遊戲開發中非常大的二進位資產（100GB+），Perforce 的集中式模型可以優於 Git LFS。

8. 故障排除和常見問題

問題解決方案
未找到 git-lfs安裝 git-lfs 並執行 git lfs install
伺服器上不存在物件git lfs fetch --all 同步指標
LFS 合併衝突LFS 合併驅動程式自動解析（選擇一個版本）
驗證錯誤設定 credential.helper 與 lfs.<url>.access
頻寬超出升級計劃或等待計費週期重置

結論

Git LFS 是 Git 中大檔案的事實上的標準。關鍵要點：儘早追蹤模式，透過團隊協調仔細遷移，監控儲存和頻寬配額，透過選擇性獲取優化 CI，並使用 git lfs prune 定期清理。在專案設定初期制定 LFS 指南，而不是稍後進行改造。對於特定於 ML 的工作流程，評估 DVC；對於海量二進位資產，請考慮 Perforce 或 Git Annex。

©2022 - 2026 Commentary of Takao