Menu

© 2026 ういやまラボ

JPEN
BLOGTOOLSPRODUCTNOTES
リストに戻る

【Unreal Engine】UEプロジェクトをGitで安全に管理する：.gitignore・LFS・One File Per Actor

作成: 2026-07-20

UE5プロジェクトをGitに入れる正しい設定。コミットしてはいけないフォルダ、.gitignoreと.gitattributesの中身、なぜ.uassetにGit LFSが必要か、バイナリはマージできないのでロックで守る話、One File Per Actorで競合が減る仕組みまでを図解。

UEでゲームを作り始めて、そろそろバックアップしたい。友達と共同で開発したい。Gitを使えばいいと聞いたので、プロジェクトフォルダをまるごと git add . してコミットする。すると、数GBの巨大なコミットが出来上がり、次の日には履歴が膨れ上がって手がつけられなくなります。

UEプロジェクトは、他の多くのプロジェクトと事情が違います。アセットがバイナリで、しかも巨大 だからです。1つのレベルが数百MBになることも珍しくありません。何も考えずにGitへ入れると、すぐに破綻します。この記事では、UEプロジェクトをGitで安全に管理するための3つの柱、除外するフォルダ・Git LFS・ロック を解説し、最後に正しい設定で初回コミットするところまでやります。

巨大なプロジェクトフォルダが、正しい設定で軽いリポジトリになる様子とソフトブルーのクレイ人形

この記事でわかること

  • コミットしてはいけないフォルダ（Saved / Intermediate / DerivedDataCache / Binaries）
  • なぜ .uasset に Git LFS が必要なのか
  • バイナリは マージできない ので、ロックで守る
  • One File Per Actor で複数人の競合が減る仕組み
  • 実践： 新規プロジェクトを、正しい設定で初回コミットする

目次

Sponsored

コミットしてはいけないフォルダ

UEプロジェクトのフォルダには、あなたが作ったもの と、エンジンが自動生成したもの が混ざっています。Gitに入れるべきは前者だけです。

自動生成されるフォルダは、コミットしてはいけません。容量を無駄に食う上に、環境ごとに中身が変わるので、共同開発で衝突の原因になります。

Content・Config・Source・uprojectはコミットする、Saved・Intermediate・DerivedDataCache・Binariesは除外する、という2グループに分けた図

除外すべき代表的なフォルダは次の4つです。

  • Saved：オートセーブやログ、一時ファイル。実行のたびに変わる。
  • Intermediate：ビルドの中間ファイル。作り直せる。
  • DerivedDataCache（DDC）：シェーダーなどのキャッシュ。巨大で、環境依存。
  • Binaries：ビルド済みの実行ファイル。ソースから作り直せる。

これらを除外するのが .gitignore の役目です。中身を自分で書く必要はありません。 GitHubでリポジトリを新規作成するとき、.gitignore テンプレートの一覧から UnrealEngine を選べば 、上記はすべて最初から除外されます。手元で用意したい場合は、GitHubの github/gitignore リポジトリにある UnrealEngine.gitignore を、プロジェクト直下へ .gitignore という名前で置いてください。逆に、コミットするのは Content（アセット本体）・Config・Source（C++）・.uproject ファイルや、自作した Plugins フォルダなどです。

Git LFSが必要な理由

.gitignore で生成物を除いても、まだ問題が残ります。アセット本体（.uasset / .umap）がバイナリ だということです。

Gitは本来、テキストの差分を管理する道具です。ソースコードのように「3行目のここが変わった」を記録するのが得意です。ところが .uasset はバイナリなので、少し変えただけでもファイル全体が別物として記録されます。編集するたびに、ファイル1個まるごとが履歴に積み上がっていきます。

テキストは変更行だけ記録されるが、バイナリのuassetは変更のたびにファイル全体が履歴に積み上がる様子を対比した図

これを解決するのが Git LFS（Large File Storage） です。LFSは、大きなバイナリを履歴の本体から切り離し、別の場所に保管します。履歴には「このファイルはあそこにある」という小さな目印だけを残すので、リポジトリ本体が軽く保たれます。

どのファイルをLFSに乗せるかは、.gitattributes に書きます。

*.uasset filter=lfs diff=lfs merge=lfs -text
*.umap   filter=lfs diff=lfs merge=lfs -text
*.fbx    filter=lfs diff=lfs merge=lfs -text
*.wav    filter=lfs diff=lfs merge=lfs -text

.uasset と .umap は必須です。ほかにインポート元のFBXや音声・大きな画像なども、バイナリで容量が大きいものはLFSに乗せます。

Sponsored

バイナリはマージできない

Git LFSでも解決できないことが1つあります。バイナリはマージできない という事実です。

テキストなら、2人が別々の行を編集しても、Gitが自動でマージできます。ところが .uasset はバイナリなので、2人が同じアセットを触ると、Gitは「どちらが正しいか分からない」となり、片方で上書きするしかなくなります。片方の作業が丸ごと消えます。

2人が同じuassetを編集すると、テキストと違ってマージできず片方の変更が失われる様子と、ロックで防ぐ様子を並べた図

これを防ぐのが ファイルロック です。誰かがアセットを編集する前に git lfs lock でロックすると、他の人はそのファイルを編集できなくなります。「今このマップは私が触っています」という札を立てるイメージです。作業が終わってpushすれば、ロックが外れます。ロックを本格的に運用するなら、.gitattributes に *.uasset lockable のように lockable 属性を足しておくと、ロックせずに編集しようとしたときに警告が出るようになります。

もう1つ、UE5には競合そのものを減らす仕組みがあります。One File Per Actor（OFPA） です。World Partitionを使うと、レベルに置いた各Actorが個別のファイルとして保存されます。1つの巨大な .umap を全員で奪い合う代わりに、Actorごとにファイルが分かれるので、別々のActorを触っている限りぶつかりません。

Sponsored

実践：正しい設定で初回コミット

規模やジャンルに関係なく、全員が最初に一度だけやる作業です。ここを正しくやるかどうかで、この先の運用が決まります。

新規プロジェクト（テンプレートでも自作でも可）を、正しい設定で初回コミットします。

動かすとこうなります。.gitignore と LFS を設定してからコミットすると、数GBあったはずのプロジェクトが、数十MB程度の軽いコミットになります。

gitignore設定前は数GBの巨大コミット、設定後は数十MBの軽いコミットになる容量の前後比較図

手順

前提として、Gitと Git LFS の本体を先にインストール し（LFSはGitとは別のツールです）、git config で user.name と user.email を設定しておきます。準備ができたら、プロジェクトのルートフォルダ（.uproject がある場所）で、次の順に実行します。

# 1. リポジトリを初期化
git init

# 2. このリポジトリにGit LFSを組み込む（LFS本体は事前にインストール済みとする）
git lfs install

# 3. .gitignore と .gitattributes をルートに置く
#    .gitignore   … Saved/ Intermediate/ DerivedDataCache/ Binaries/ などを除外
#    .gitattributes … *.uasset *.umap などを filter=lfs で登録

# 4. .gitattributes を先にコミットしておく（LFSの対象を確定させる）
git add .gitattributes .gitignore
git commit -m "Add gitignore and LFS attributes"

# 5. 残りをコミット
git add .
git commit -m "Initial commit"

順番が重要です。.gitattributes を置いてから git add . する ことで、.uasset が最初からLFSに乗ります。設定より先にアセットをコミットすると、LFSに乗らず履歴に直接入ってしまい、後で取り除くのが面倒になります。

git init→lfs install→gitattributes配置→コミットの順に進む初回セットアップのフロー図

確かめる

コミットが終わったら、2つのコマンドで確認します。

  • git status を実行して、Saved/ や Intermediate/ が出てこない こと。出てくるなら .gitignore が効いていません。
  • git lfs ls-files を実行して、.uasset が一覧に並ぶ こと。並ばないなら、.gitattributes を置く前にコミットしてしまっています。

この2つが期待通りなら、設定は成功です。もしLFSに乗っていなかったら、まだ他人と共有していないうちに、次の手順をやり直すのが一番簡単です。

ポイントは2つです。

  • 設定ファイルを最初に置く：.gitignore と .gitattributes は、アセットをコミットする前に必ず配置する。順番を逆にすると、大きなバイナリが履歴に焼き付いて取れなくなる
  • 生成物は入れない・アセットはLFS：この2つが守れていれば、リポジトリは軽く保たれる。git status と git lfs ls-files で毎回の確認が効く

初回コミットまで終われば、あとは パッケージ化 や日々の開発を、安心して積み重ねられます。

おまけ：先に知っておくと良いこと

途中からLFSに移すこともできる。 すでに .uasset を普通にコミットしてしまった場合でも、git lfs migrate import --include="*.uasset,*.umap" のように対象を指定すれば、過去の履歴をLFSに移し替えられます。ただし履歴を書き換えるので、他人と共有する前に済ませるのが安全です。

ローカルのコミットはバックアップではない。 git commit はPCの中に記録を残すだけです。PCが壊れたら消えます。GitHubなどにリモートを作って git push して、はじめてバックアップになります。共同開発する場合も、各自のPCにGit LFSを入れ、LFSに対応したリモート経由でアセットを共有します。

大きいファイルは一度入れると消えない。 Gitは履歴を保持するので、大きなバイナリを入れて後で削除しても、履歴には残り続けます。cloneのたびにその容量が付いて回ります。「入れない」ことが最大の対策です。

チーム規模が大きいならPerforceも。 大人数でバイナリを激しく編集する現場では、ロックが標準のPerforceやDiversionが選ばれることもあります。ただ、個人開発や少人数なら、Git + LFS で十分に回ります。まずはGitから始めて、困ったときに他を検討すれば大丈夫です。

まとめ

UEプロジェクトのGit管理は、最初の設定がすべてです。生成物フォルダを .gitignore で除き、.uasset を .gitattributes でLFSに乗せ、この2つをアセットより先に置く。複数人なら、バイナリはマージできないのでロックとOFPAで競合を避ける。ここさえ押さえれば、リポジトリは軽く、履歴はきれいに保てます。

あなたのプロジェクトは今、git status にSaved/やIntermediate/が並んでいないでしょうか。一度確認してみてください。