BFGを使ったGitリポジトリのGit LFSへのマイグレーション

caution
以下のドキュメントは非推奨です。以下のドキュメントの代わりに git lfs migrateを使うことを推奨します。

Git LFS を使うと、Git リポジトリのサイズを小さくしてパフォーマンスを向上させることができます。

しかし、すでにリポジトリにある大きなファイルを Git LFS に追加しても、実際にリポジトリのサイズが小さくなるわけではありません。

この文書で説明する方法で、まずオープンソースコミュニティが管理しているBFGなどのツールを使ってミラーリポジトリから Git LFS にマイグレーションし、リポジトリの履歴をクリーンアップして、最後に LFS のトラッキングルールを作成して新しいバイナリファイルが追加されないようにします。

このチュートリアルは、Use BFG to migrate a repository to Git LFS を参考にしました。Git LFS についての詳細は、以下のリファレンスを参照ください。

caution
このガイドで説明する方法は、Git の履歴を書き換えるものです。始める前に必ずリポジトリのバックアップを取り、自己責任で使用してください。

前提条件

始める前に

  • 変換するファイルに十分な LFS ストレージがあること。すべてのファイルの全履歴に対してストレージが必要です。
  • リポジトリを共有しているチームメンバー全員がすべての変更をプッシュしていること。この方法を適用する前のリポジトリに基づくブランチはマージできません。

このチュートリアルに従うには

  • LFS にマイグレーションしたい既存の Git リポジトリのメンテナー・ロール。
  • GitJava ランタイム環境(Java 7 以上)がローカルにインストールされていること。
  • BFGがローカルにインストールされていること:

     brew install bfg
    
  • Git LFSがローカルにインストールされています:

     brew install git-lfs
    
note
このガイドはmacOS Mojaveでテストされています。

ステップ

アップストリームプロジェクトの例git@gitlab.com:gitlab-tests/test-git-lfs-repo-migration.git を考えてみましょう。

  1. リポジトリをバックアップしてください:

    リポジトリのコピーを作成し、何か問題が発生したときに復旧できるようにしてください。

  2. Clone--mirror リポジトリをクローンします:

    ミラーフラグでクローンすると、ベアリポジトリが作成されます。これにより、リポジトリ内のすべてのブランチを取得できるようになります。

    <repo-name>.git というディレクトリが作成され(この例ではtest-git-lfs-repo-migration.git)、アップストリームプロジェクトがミラーされます:

    git clone --mirror git@gitlab.com:gitlab-tests/test-git-lfs-repo-migration.git
    
  3. BFGでGit履歴を変換します:

    bfg --convert-to-git-lfs "*.{png,mp4,jpg,gif}" --no-blob-protection test-git-lfs-repo-migration.git
    

    すべての履歴をスキャンし、その拡張子のファイルを探して LFS ポインタに変換します。

  4. リポジトリをクリーンアップします:

    # Change into the mirror repo directory:
    cd test-git-lfs-repo-migration.git
       
    # Clean up the repo:
    git reflog expire --expire=now --all && git gc --prune=now --aggressive
    

    リポジトリをさらにクリーンアップする方法を見ることもできますが、このガイドの目的には必要ありません。

  5. ミラーリポジトリに Git LFS をインストールします:

    git lfs install
    
  6. デフォルトブランチの保護を解除して、書き換えたリポジトリを強制プッシュできるようにします:

    1. プロジェクトの設定 > リポジトリを開き、保護ブランチを展開します。
    2. 下にスクロールして保護ブランチを探し、デフォルトブランチの保護を解除を選択します。
  7. GitLab に強制プッシュします:

    git push --force
    
  8. LFSで必要なファイルを追跡

    # Change into the /tmp directory
    cd /tmp
       
    # Clone the repo
    git clone git@gitlab.com:gitlab-tests/test-git-lfs-repo-migration.git
       
    # Change into the upstream repo directory:
    cd test-git-lfs-repo-migration
       
    # You may need to reset your local copy with upstream's `main` after force-pushing from the mirror:
    git reset --hard origin/main
       
    # Track the files with LFS:
    git lfs track "*.gif" "*.png" "*.jpg" "*.psd" "*.mp4" "img/"
       
    # Push up changes to .gitattributes
    git add .gitattributes && git commit -m 'Track .gif,.png,.jpg,.psd,.mp4 and img/' && git push
    

    変換した既存のファイルや追加した新しいファイルは、LFSで適切に追跡されます。

  9. デフォルトブランチを保護し直します

    1. プロジェクトの設定 > リポジトリを開き、保護ブランチを展開します。
    2. ブランチドロップダウンリストからデフォルトブランチを選択し、プッシュとマージの許可と マージの許可のルールを設定します。
    3. 保護]を選択します。

リファレンス