2025/04/30

用一行指令搞定 Git 歷史中的大檔案：git lfs migrate import

用一行指令搞定 Git 歷史中的大檔案：git lfs migrate import

如果你曾經在推送 Git 專案到 GitHub 時遇到以下錯誤訊息：

remote: error: File opencv2.framework/Versions/A/opencv2 is 236.31 MB; this exceeds GitHub's file size limit remote: error: GH001: Large files detected. You may want to try Git Large File Storage

那麼你就遇到 GitHub 強制限制：單一檔案不可超過 100MB。而這個限制，不只是針對目前版本的檔案，就算該檔案只曾出現在 Git 歷史中一次，也會導致整個 Push 被拒絕。

常見的錯誤誤解


  • ❌ 單純加到 .gitignore 是無效的，因為 Git 歷史已經記錄過
  • ❌ 使用 git lfs track 只能對未來新 commit 有效，無法 retroactively 處理歷史
  • ✅ 正確解法：使用 git lfs migrate import 將歷史中的大檔搬到 Git LFS

一行指令搞定歷史大檔案

假設你遇到的問題包括多個模型檔（.mlmodel、.onnx），以及像 opencv2 這樣無副檔名的大型 Framework 檔案，以下這一行指令就能完整處理： 

git lfs migrate import --include="*.mlmodel,*.mlmodelc,*.onnx,DetectionKit-Shared/MLModel/**,opencv2.framework/Versions/A/opencv2" --everything

這會：

  • 掃描整個 Git 歷史（所有 branch、所有 tag）
  • 將指定副檔名與路徑的檔案轉為 Git LFS 專屬格式
  • 自動產生 .gitattributes 設定檔

接著強制推送乾淨的版本

因為這會更動 commit ID（但不會改變 branch 結構），你需要重新設定遠端並強制推送至 GitHub： 


git remote remove origin || true
git remote add origin git@github.com:your-org/your-repo.git
git push origin --mirror --force

注意： 所有團隊成員都需要重新 clone，此為不可避免的副作用。

如何預防未來再次出錯？

建議你在專案初始化時就建立正確的 LFS 設定：


git lfs track "*.mlmodel"
git lfs track "*.framework"
git add .gitattributes
git commit -m "Setup Git LFS tracking for large files"

結語

當面對 GitHub 嚴格的大檔案限制，git lfs migrate import 是目前最有效、最乾淨的解法。它能讓你保留完整 Git Tree 結構的情況下，從歷史中安全搬移大檔到 Git LFS。

如果你不想重寫 Git 歷史、卻又必須處理大型模型檔、Framework、甚至是沒有副檔名的裸檔案，這一行指令就是你的最佳解方。

📌 延伸閱讀：Git Large File Storage 官方網站

By at
標籤: ,