GitLab LFSを試してみた #GitLab
おはようございます( ◜◡◝ )
ゲームソリューション部のきだぱんです。
本ブログはClassmethod SaaSで加速するゲーム開発 Advent Calendar 2025とGitLab Advent Calendar 2025の24日目のブログとなります！メリクリ！
みなさん、GitLab使ってますか？🦊
ゲーム開発が進むにつれて、プロジェクトのリポジトリサイズが数十GB、数百GBと膨れ上がり、管理や時間を取られるといったこともあるかと思います。
UnityやUnreal Engineのプロジェクトでは、高解像度テクスチャ、3Dモデル、高音質なオーディオデータなど、Gitが本来苦手とする巨大なバイナリファイルが大量に扱われます。
これらをそのままGitで管理すると、履歴が蓄積されるたびにリポジトリは重くなり、開発効率は著しく低下してしまいます。
そこで救世主となるのが Git LFS (Large File Storage) です。
本記事では、Git LFSをGitLabで導入するための手順を書いていきます！
プロジェクトで Git LFS を有効にする
SaaS版のGitLabでは、デフォルトでLFSが有効になっていますが、プロジェクトごとの設定画面から確認・変更が可能です。
-
GitLabにログインし、対象のプロジェクトを表示します
-
左サイドバーの下部にある [Settings]（設定） > [General]（全般） をクリックします
-
[Visibility, project features and permissions] セクションを展開します
-
一覧の中にある [Git Large File Storage (LFS)] を「ON」にします
設定を変更した場合は、ページ下部の [Save changes] を忘れずに！！
Git LFSの仕組みを簡単に理解する
- ポインタファイル: 実ファイルの代わりに、IDやサイズが書かれた数行のテキストファイルがGitにコミットされる
- 自動ダウンロード:
git checkout時に、LFSクライアントが背後で実ファイルをダウンロードしてくれるため、ユーザーは通常のGit操作と変わらない感覚で使える
準備
- Git LFSクライアントのインストール
# (macOS)
brew install git-lfs
- 初期化
git lfs install
これによって、Git LFSが有効になります！
GitLabでの設定と使い方
リポジトリで実際に使い始める手順をステップバイステップで解説します。
- 追跡するファイル形式を指定
git lfs track "*.iso"
- 設定ファイル（.gitattributes）を保存
git lfs trackを実行すると.gitattributesが生成されるので、これを必ずコミットに含める必要がある
git add .gitattributes
git commit -m "test files"
- 通常通りファイルをプッシュ
cp ~/[kida-test] .
git add [kida-test]
git commit -m "test file"
git push origin main
GitLabを見に行くと先ほどのファイルがありました！LFSというマークも付いてます！
できました！
補足
認証が必要
普段 git@gitlab.com:...（SSH）でクローンしている場合でも、LFSの実ファイルはHTTPS経由でダウンロードされます。そのため、クローン時にGitLabのユーザー名とパスワード（またはPersonal Access Token）を求められることがあります。
最新のLFSファイルを個別に取得する
リポジトリがすでに手元にある状態で、LFSオブジェクトだけを最新に更新したい場合は以下のコマンドを使います。
git lfs fetch origin main
プランによる制限
リポジトリやLFSオブジェクトの合計サイズにはプランごとの制限があります。
- 使用量の確認方法: プロジェクトの [Settings] > [Usage Quotas]（利用クォータ） から、LFSファイルがどれくらいの容量を占有しているかリアルタイムで確認できます。
ポインタファイルとは何か？
Git LFSを導入すると、Gitリポジトリ（.git）の中にはファイルの実体ではなく、**「ポインタ」**と呼ばれる小さなテキストファイルだけが保存されます。
ポインタファイルの例
# ポインタファイルの例
version https://git-lfs.github.com/spec/v1
oid .....
size 185905
※GitLabのバージョン13.5以降では、Webからプロジェクトをダウンロード（アーカイブ作成）する際に、このポインタを自動的に実ファイルに差し替えてくれるようになっています。
既存リポジトリからの移行
すでにリポジトリが巨大化してしまっている場合は、git lfs migrate を使って過去の履歴ごとLFSに移行する必要があります。
リポジトリから完全にファイルを消し去るには、git filter-repo などのツールを使用して履歴を書き換えた後、.gitattributes から該当の行を削除する手順が必要です。
※履歴の書き換えはmember全員に影響します
トラブルシューティングは、ブログの信頼性を高める非常に重要なセクションですね。特にゲーム会社では、膨大なアセット
エラーした場合
プッシュやプルをした際に「status: 501」というエラーが出ることがあります。これは多くの場合、**「LFSの設定が有効になっていない」**ことが原因です。
まずは以下のコマンドでログの詳細を確認しましょう。
git lfs logs last
前述の通り、GitLab SaaSのプロジェクト設定で「Git LFS」がONになっているか再確認してください。
LFSオブジェクトが見つからない場合
GitLabはプッシュ時に、ファイルが「LFSポインタ」かどうかをチェックし、その実体がちゃんとLFSストレージに存在するかを確認します。ここでエラーが出る場合は、実ファイルがサーバーに届いていない（同期が不完全な）状態です。
ローカルにLFSがインストールされているか改めて git lfs install を実行しましょう！
欠けているファイルを全て強制的にプッシュし直すことで解決する場合があります。
git lfs push --all origin
おわりに
今回は、GitLabでGit LFSを導入する手順を書きました！
Git LFSを適切に導入することで、リポジトリの肥大化を防ぎ、チーム全員が快適に開発を続けられる環境を作ることができます！
ぜひ、ご自身のプロジェクトでも試してみてください！
DevelopersIOでは、GitLabに関するブログも展開されていますので、是非こちらもご覧ください。
以上、きだぱんでした！
