• 前提条件
• ステップ
• リファレンス

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

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

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

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

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

前提条件

始める前に

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

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

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

• BFGがローカルにインストールされていること：

   brew install bfg
  

• Git LFSがローカルにインストールされています：

   brew install git-lfs
  

ステップ

アップストリームプロジェクトの例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. 保護]を選択します。

リファレンス

• Git LFS のはじめかた
• GitLab Git LFS ユーザードキュメント
• GitLab Git LFS 管理者向けドキュメント
• 既存のリポジトリを Git LFS にマイグレーションする別の方法