全部產品
Search
文件中心

Alibaba Cloud DevOps:LFS 遷移指南

更新時間:Dec 05, 2025

本文主要協助您在Codeup倉庫中啟用大檔案儲存體( LFS)以更高效地管理二進位檔案,並提供第三方程式碼程式庫遷移到Codeup時的LFS檔案遷移方案。

適用情境

分為以下幾種情況,請對照實際情況,執行相應的操作:

  • Codeup倉庫-啟用LFS。

  • Codeup倉庫-啟用LFS,並修改歷史提交中的檔案至LFS管理。

  • 遷移第三方程式碼程式庫至Codeup-啟用LFS。

  • 遷移第三方程式碼程式庫至Codeup-啟用LFS,並修改歷史提交中的檔案至LFS進行管理。

  • 遷移已經啟用了LFS的第三方程式碼程式庫至Codeup管理。

LFS 的安裝和基本使用

請參見如何使用Git LFS?, 安裝完成後,可以運行:

$ git lfs -v

來查看LFS是否正確安裝及對應版本。

在Codeup中使用LFS管理二進位檔案

Codeup 程式碼程式庫-啟用LFS

假設倉庫的歷史提交中不存在希望使用 LFS 管理的大檔案(二進位檔案),或者本身就是從空庫開始,操作會非常簡單。以下為如何在一個不需要修改歷史提交的 Codeup 庫上,開啟並使用 LFS 功能。

  1. 備份倉庫:強烈建議在操作前備份倉庫。以下命令用於備份倉庫至本地的 backup 檔案夾:

    $ git clone --bare gi*@codeup.aliyun.com:<組織或組id>/<倉庫地址> backup
  2. 進入本地倉庫:備份完成後,進入本地已有的倉庫,或者重新複製,作為工作目錄。假如我們要將 png 的圖片檔案使用 LFS 進行管理,執行:

    $ git lfs track "*.png"
    Tracking "*.png"

    然後,向倉庫中加入 png 檔案,例如:

    $ echo test > test.png
  3. 提交改動:執行 add 以及 commit,並將改動推送到遠端倉庫。

    $ git add .
    $ git commit -m "使用LFS管理png檔案"
    $ git push

    輸出中會看到 Uploading LFS objects done 的相關字樣,說明 LFS 已經啟用,對應檔案也已上傳。

    開啟程式碼程式庫頁面,可以看到 lfs.png 已經被標記為使用 LFS 管理了。

    在程式碼程式庫設定 > 大檔案儲存體的管理頁面,也能看到LFS對象的總體積,類型,提交者等資訊。隨後,重新複製一次倉庫。執行:

    $ git clone gi*@codeup.aliyun.com:<組織或組id>/<倉庫地址>

    可以看到,png檔案被自動的檢出,並不需要額外的操作。

Codeup倉庫-啟用LFS,並修改歷史提交中的檔案至LFS管理

在很多情況下,我們已經向倉庫中添加了許多大檔案。開啟 LFS 只會對之後的提交生效,並不會影響這些歷史檔案。我們可以利用 git lfs migrate 命令來完成歷史檔案的遷移。

  1. 備份倉庫:首先,建議將倉庫進行備份:

    $ git clone --bare $ gi*@codeup.aliyun.com:<組織或組id>/<倉庫地址> backup

    建議按照分支進行遷移,一次遷移一個分支。

  2. 倉庫複製及遷移分支:在倉庫複製時,請複製為裸倉庫,來完整擷取遠程倉庫所有引用,避免出現遺漏,導致部分歷史分支、引用中的歷史提交沒有完成遷移。

    git clone --mirror <遠程倉庫 URL> <本地目錄名>

    進入裸倉庫目錄,執行:

    $ git lfs migrate import --include-ref=master --include="*.png"

    會看到類似的輸出:

    migrate: Sorting commits: ..., done.
    migrate: Rewriting commits: 100% (2/2), done.
      master 2d2c813aac4b2247e4b79b3721cca45580f15282 -> 5634c182663a24617bd26d0d82a3966686687173
    migrate: Updating refs: ..., done.
    migrate: checkout: ..., done.

    可以看到,歷史的提交已被改寫,這樣就遷移了 master 分支上的歷史 png 檔案至 LFS 管理

  3. 遷移其他分支和引用:例如遷移 dev 分支,執行:

    $ git lfs migrate import --include-ref=dev --include="*.png"

    如果有其他分支和引用,進行類似的操作即可。

  4. 推送遷移後的裸倉庫:行以下命令,將遷移後的分支和標籤推送至遠端:

    $ git push --mirror --force

    這樣一來,歷史的 png 檔案也被 LFS 管理起來。之後添加的 png 檔案,也會由 LFS 來進行管理。

  5. 如果分支特別多的情況下,可以選擇一次性遷移所有分支。執行以下命令可以遷移本地所有分支的歷史png圖片至LFS管理:

    $ git lfs migrate import --everything --include="*.png"
    說明
    • 一次性遷移所有分支,可能導致上傳檔案逾時等問題。如果出現類似的問題,建議按照分支逐個遷移。

    • 如果您的倉庫之前在Codeup託管,且有合并請求歷史,在您的裸倉庫中會出現形如refs/changes/1、refs/changes/1/head、refs/changes/1/target/1的、用於記錄合并請求歷史的特殊引用,在進行遷移的時候,需要指定--everything,將上述引用一併進行遷移。

遷移第三方程式碼程式庫至Codeup-啟用LFS

如果希望遷移其他平台的倉庫至Codeup,並且啟用LFS,那麼可以這樣操作:

  1. 在Codeup上匯入其他平台的倉庫。

  2. 完成後按照Codeup 程式碼程式庫-啟用LFS,開啟LFS。

遷移第三方程式碼程式庫至Codeup-啟用 LFS,並修改歷史提交中的檔案至LFS進行管理

如果已經在其他平台啟用了LFS,此時想要將倉庫遷移至Codeup,可以按照以下步驟操作:

  1. 參考Codeup倉庫-啟用LFS,並修改歷史提交中的檔案至LFS管理中的前三個步驟,遷移本地所有分支的歷史提交,但不執行git push的操作。

  2. 在執行git push操作前,執行:

    $ git remote add codeup <Codeup倉庫地址>
  3. 執行:

    git push --all --force codeup
    git push --tags --force codeup
  4. 開啟Codeup的倉庫頁面,就能看到倉庫已經成功上傳。

遷移已經啟用了LFS的第三方程式碼程式庫至Codeup管理

如果已經在其他平台啟用了LFS,此時想要將倉庫遷移至Codeup,那麼可以按照以下步驟操作:

  1. 首先,執行一次全量的複製:

    $ git clone --bare <其他倉庫的地址>
  2. 然後,將LFS的檔案都下載到本地:

    $ git lfs fetch --all origin
  3. 下載完成後,修改倉庫的remote地址至Codeup:

    $ git remote add codeup gi*@codeup.aliyun.com:<組織或組id>/<倉庫名稱>
  4. 然後,推送LFS檔案到Codeup:

    $ git lfs push --all codeup
  5. 完成後,接著執行:

    $ git push --all codeup
    $ git push --tags codeup

    這樣,就完成了已有LFS倉庫遷移至 Codeup 的操作。

重要

如果遷移的LFS檔案體積較大,在推送倉庫時可能會出現超過伺服器串連時間長度限制等情況。具體表現為 git push 命令推送 LFS 檔案後即結束,不更新遠程倉庫的引用。如果出現這樣的問題,可以將推送操作分兩步執行:

  1. 首先使用git lfs push --all origin命令,推送LFS檔案至伺服器。

  2. 使用git push --all --no-verify命令,跳過LFS檔案的推送及檢查,並更新遠程倉庫的引用。

關於LFS的更詳盡使用說明,請參見 Codeup Git LFS 功能簡介