扉のギミックが動いたので、今の状態を残しておきたい。友達が作ったステージも受け取りたい。そこでUEプロジェクトをGitへ追加すると、アセットだけでなく、大量のログや一時ファイルまで候補に並ぶことがあります。
まず決めたいのは、何を記録し、何を記録しないか です。そのうえで、大きなアセットを扱うGit LFSと、同じアセットの同時編集を避けるロックを使います。それぞれの役割が分かると、設定ファイルの意味も追いやすくなります。
この記事では、小さなUEプロジェクトを最初に記録するところまで試します。最後は容量の数字ではなく、必要なファイルが揃い、生成物が除外され、アセットがLFSで記録されているか で確かめます。
この記事でわかること
- commit・pushと、2つの設定ファイルの役割
- UEで残すファイルと、除外する生成物
- LFSを使った初回コミットと確認方法
- ロックとOne File Per Actorで同時編集を整理する方法
Gitへ記録するまでの流れ
Git は、ファイルの変更を履歴として残す道具です。「扉を追加した時点」「敵の攻撃が動いた時点」のように区切って記録すると、変更内容を確認したり、以前の状態へ戻したりできます。履歴を管理する場所を リポジトリ と呼びます。
| 操作 | 何をするか |
|---|---|
git add | 次の記録へ含める変更を選ぶ。選んだ状態を「ステージする」ともいう |
git commit | 選んだ内容を、説明文付きで手元の履歴へ残す |
git push | 手元の記録を、GitHubなど別の保存先へ送る |
git clone | 共有先からリポジトリを取得し、別の作業フォルダを作る |
commitしただけでは、記録は同じPCの中です。 PC故障に備えるなら、別の場所にも記 録を持つ必要があります。その共有先を「リモート」と呼びます。今回はまず手元で正しく記録し、共有時の確認も後半で扱います。
UEでのファイル保存も先に必要です。エディタで変更したまま保存していない内容は、Gitから見えません。ゲームを保存してから、作業の区切りでcommitする、という順序になります。
残すファイルと、除外する生成物
プロジェクトの中には、アセットや設定と、エンジンが作る一時データが混ざっています。判断の軸は、そのファイルがないと、自分や相手が同じプロジェクトを開けなくなるか です。
| 記録するもの | 中身 |
|---|---|
.uproject | プロジェクトの情報 |
Content/ | Blueprint、マップ、マテリアルなどのアセット |
Config/ | プロジェクトの設定 |
Source/ | C++のコード。Blueprintだけなら存在しない場合もある |
必要な Plugins/・Build/ など | 自作プラグインや、ビルドに使う設定・素材 |
フォルダ構成の考え方は アセット管理の記事 でも扱っています。一方、次は通常の開発履歴から除外する代表例です。
| 除外するもの | 理由 |
|---|---|
Saved/ | ログ、オートセーブ、実行時の保存など。作業ごとに変わる |
Intermediate/ | ビルド途中に作るファイル。再生成できる |
DerivedDataCache/ | シェーダーなどの処理結果を再利用するキャッシュ |
プロジェクト直下の Binaries/ | ビルド済みファイル。自分のソースと開発環境から再生成する運用なら除外する |
除外は、ディスクから削除するという意味ではありません。 Gitの記録へ含めないだけです。Savedにしかないオートセーブを救出したいときは、履歴管理とは別に扱います。
この除外規則を書くファイルが .gitignore です。新しく追加する候補から外すためのもので、既に記録済みのファイルを自動で取り除くものではありません。
Binariesをどこでも一律に除外しない
ソースが付いていないプラグインなど、自分で再生成できないバイナリもあります。プラグ インの配布形態と復元方法を確認して残します。同じ理由で、Buildやインポート元の画像・音声を丸ごと不要とは決めません。
LFSはアセットの保存先を分ける
UEの .uasset や .umap は、エンジンが読む バイナリ形式 のファイルです。Blueprintのノードも、Git上では人が読めるソースコードの行として保存されているわけではありません。
大きなアセットを何度も更新すると、その履歴の保管や取得が重くなります。Gitにも圧縮の仕組みはありますが、大きなアセットの運用では Git LFS（Large File Storage） を使い、実データの保存先を分けます。
LFSを使うと、Gitの履歴には ポインタ という小さな目印が入り、アセット本体はLFS側へ保管されます。目印には「どの実データか」を特定する情報があり、取得時にはそれを使って本体を取り出します。作業フォルダには、UEで開ける元のアセットが置かれます。
つまり、LFSはアセットを数GBから数MBへ縮める仕組みではありません。Gitの履歴と大きな実データを分ける仕組み です。LFS側にも保存容量が必要で、共有サービスの容量・転送量の条件は確認します。
どのファイルをLFSで扱うかは .gitattributes に記録します。.gitignore が「記録から外す規則」なのに対し、こちらは「記録するファイルの扱い方」です。
*.uasset filter=lfs diff=lfs merge=lfs -text
*.umap filter=lfs diff=lfs merge=lfs -text
この2行は「拡張子がuassetとumapのファイルを、LFS経由で読み書きする」という指定です。次の実践ではコマンドから作るので、最初から各項目を暗記する必要はありません。大きなFBXや音声なども同じリポジトリへ置くなら、必要な拡張子を追加します。
実践：LFSを設定して初回コミット
まだGitへ追加していない、小さな練習用UEプロジェクト を使います。Third Personテンプレートなど、Contentにアセットがあるものにしてください。初期設定の記事 で既にコミットしたプロジェクトを使う場合は、末尾の「途中からLFSにする」を先に確認します。
① 実行する場所を確かめる
GitとGit LFSをインストールし、ターミナルで次を実行します。どちらもバージョンが表示 されれば、本体を呼び出せています。導入先は Git公式 と Git LFS公式 です。
git --version
git lfs version
UEで「Save All」し、エディタを閉じます。.uproject があるフォルダでターミナルを開いて、次を実行します。Windowsではエクスプローラーの「ターミナルで開く」などが使えます。
git init
git lfs install --local
git init は、そのフォルダで履歴管理を始める操作です。--local は今回のリポジトリにLFSの設定を入れる指定で、LFS本体のインストールとは別です。
② 除外とLFSの規則を用意する
.uproject と同じ階層へ、テキストエディタで .gitignore を作ります。追加プラグインのない練習用として、まず次を入れます。
/Saved/
/Intermediate/
/DerivedDataCache/
/Binaries/
/.vs/
/*.sln
先頭の / は、プロジェクト直下を指定しています。この例ではPlugins配下を一括除外しません。C++やプラグインを追加したら、生成物と必要な配布ファイルを見て規則を足します。
GitHubの UnrealEngine.gitignore も出発点になります。ただし、プラグインのBinariesやBuild、SourceArtの画像などを除外する規則も含まれるため、中身を確かめて使います。Windowsでは .gitignore.txt という名前になっていないかも確認してください。
次に、LFSの対象を登録します。引用符も含めて実行すると、拡張子の規則が .gitattributes へ書き込まれます。
git lfs track "*.uasset"
git lfs track "*.umap"
ここまでは、記録するための準備です。 アセットを git add する前に規則を置くことで、最初からLFSの目印として記録できます。
③ 追加する内容を見てからコミットする
まず候補の一覧を見ます。
git status --short --untracked-files=all
Config、Content、.uproject、2つの設定ファイルが候補にあり、SavedやIntermediateが含まれていないか確認します。必要なものが揃っていたら追加します。
git add .gitignore .gitattributes
git add .
git diff --cached --name-only
git lfs ls-files
--cached は「次のコミットへ選んだ内容」を見る指定です。最初の一覧で生成物が混ざっていないこと、LFSの一覧で .uasset や .umap が並ぶことを確かめます。ここで問題があれば、まだコミットせず設定を見直します。
git commit -m "Add UE project with Git LFS"
初回に名前・メールアドレスを求められた場合は、Gitの案内に従って user.name と user.email を設定し、コミットをやり直します。この情報は履歴の作者欄に記録されます。
設定ファイルを別のコミットに分けることもできますが、先にコミットすることが必須なのではなく、アセットを追加する時点で規則が有効なこと が大切です。
④ 「一覧が空だから成功」で終わらせない
コミット後の git status --short が空なら、未記録の変更はありません。ただし、間違って生成物までコミットしていても空になります。次の一覧も見ます。
git ls-files -- Saved Intermediate DerivedDataCache Binaries
git lfs ls-files
git log -1 --oneline
- 最初のコマンドが空：指定した生成物フォルダは記録されていません。
- 2番目にアセットが並ぶ：そのファイルがLFSで記録されています。
- 最後にコミットの説明が出る：今回の記録が作られています。
除外規則そのものも見たい場合は、たとえば git check-ignore -v Saved/Logs/check.log を実行します。ファイルが実在しなくても、そのパスに当たる規則を調べられます。
⑤ 変更を1つ記録してみる
UEを開き、練習用レベルへCubeを1つ追加して保存します。もう一度エディタを閉じ、git status --short と git lfs status を見てください。保存したマップなどが変更として現れます。
変更対象を確認してから git add .、git commit -m "Add practice cube" と進めます。git log -2 --oneline に2つの記録が並べば、設定だけでなく日々の作業も残せています。
World Partition（広いレベルを分割して扱う仕組み）を使うレベルでは、マップ本体ではなくActor用の別ファイルが変わることがあります。これは後で説明するOFPAの働きです。ファイル名が見慣れなくても、変更を確かめずに除外しないでください。
共有先から開き直せるかも確認する
リモートを使うときは、Git LFS対応の保存先を登録してpushします。Gitの履歴とLFSの実データ、両方のアップロードが成功 したことを確認してください。
取得する側にもGit LFSをインストールし、git lfs install でそのユーザーの初期設定を済ませます。別フォルダへcloneし、同じUEバージョンと必要なプラグインを用意して .uproject を開ければ、共有できる状態かを確かめられます。C++プロジェクトでは再ビルドも必要です。
アセット本体を取得できていない場合は、認証や容量制限を確認したうえで、取得したリポジトリ内で git lfs pull を使います。
共同編集ではロックを使う
2人が同じ扉のBlueprintを編集したとします。1人は開く速さを変え、もう1人は効果音を足しました。この2つの変更を1つにまとめるのが マージ です。
ソースコードなら行の違いを比べられますが、通常のGitは .uasset の中のノードを読み取り、意図どおりに組み合わせることはできません。競合したときに片方が自動で消えるのではなく、どちらを採用し、もう片方の変更をどう反映するかを人が決める 必要があります。
そこで、編集前に「このファイルは今、自分が使う」と予約する ロック を使います。同じアセットを順番に編集するための仕組みです。
ロックを使うための準備
LFSのファイル転送に対応していても、ロックへの対応は別途確認します。チーム全員のLFS設定と、共 有先のロック機能が必要です。
ロックを使う運用に切り替えるなら、次で対象へ lockable 属性を付け、変更した .gitattributes をコミット・共有します。
git lfs track --lockable "*.uasset"
git lfs track --lockable "*.umap"
lockable は、ロックしていないファイルを作業フォルダで読み取り専用にするための指定です。「設定すると必ず警告が出る」という意味ではありません。保存できなくなったとき、まずロックの有無を確認できます。
編集から解除まで
例として Content/Blueprints/BP_Door.uasset を編集します。自分の変更がない状態で共有先の最新状態を取り込み、次の順で進めます。
git lfs locksで使用状況を見ます。git lfs lock Content/Blueprints/BP_Door.uassetが成功してから、UEで編集・保存します。- 変更内容と関連ファイルを確認し、コミットします。
- pushが成功したことを確認します。
git lfs unlock Content/Blueprints/BP_Door.uassetで解除します。
標準のGit LFSでは、pushだけでロックは外れません。 次の人が作業できるように解除まで行います。新しい効果音アセットも加えたなら、それも一緒に記録して送ります。
ロックはチームの道具と手順を揃えて使う仕組みです。他人のPC上の変更をどんな方法でも禁止する権限管理とは異なります。競合を避けるため、担当範囲の共有も合わせて行います。
One File Per Actorで作業を分ける
照明を直したい人と、敵の配置を直したい人が、同じレベルを開いている場面を考えます。全部が1つのマップファイルに入っていると、別々のActorを触っただけでも同じファイルを編集することになります。
One File Per Actor（OFPA） は、レベルに置いたActorのデータを、それぞれ別のファイルへ保存する仕組みです。Actorは、レベルに配置する照明や敵などのことです。照明と敵の配置が別ファイルなら、作業が重なりにくくなります。
World Partitionのレベルでは標準で有効です。通常のレベルでも「World Settings → Use External Actors」で有効化できます。ただし既存レベルの保存構成が変わるため、練習用のコピーで変換と共有を試してから採用します。
分かれるのは、配置したActorのデータです。 2人が同じ敵Blueprintのアセットを編集したり、同じActorを動かしたりすれば、OFPAでも競合します。マップ側の設定変更までなくなるわけではありません。
Content/__ExternalActors__/ などにあるファイルは、読みにくい名前でも必要なデータです。マップだけを送る・戻すのでは足りない場合があります。Actorを追加・削除したときは、関連するファイルをまとめて記録してください。
おまけ：設定を間違えたとき
生成物を既にコミットした
.gitignore を後から書いても、追跡中のファイルには効きません。まず git ls-files で記録対象を確認します。不要な生成物だと確かめたパスは、git rm --cached で手元の実ファイルを残して追跡対象から外せます。フォルダなら -r も必要です。
これは次のコミットから外す操作で、過去の履歴を小さくする操作ではありません。ファイルが必要か不明な状態で、プロジェクト全体へまとめて実行しないでください。
途中からLFSにする
過去に通常のGitで記録したファイルへLFSの規則を追加しても、過去のコミットはそのままです。今後の記録から切り替えるなら、規則を用意した後で対象を追加し直す工程が必要になります。
過去の履歴も変換するには git lfs migrate という道具がありますが、履歴を書き換える方法ではコミットの識別番号も変わります。まず作業中のファイルと履歴をバックアップし、共有済みか、どの範囲を変換するかを確認します。初回セットアップのコマンドを繰り返すだけで解決したとは考えないでください。
LFSの一覧が空になる
アセットがまだない、対象の拡張子が違う、まだ追加していない、通常のGitで記録済みなど、複数の理由があります。git lfs track で規則を確認し、git lfs status でLFSが扱う変更を調べます。.gitattributes が正しい場所にあるかも見直します。
容量が増え続ける
古い大きなファイルを現在のフォルダから削除しても、過去のコミットに残っていれば履歴は保持されます。LFS側にも旧版の実データが残るため、必要な履歴と保存先の容量を管理します。キャッシュや生成物を最初から記録しない設定は、そのためにも役立ちます。
まとめ
.gitignore で生成物を外し、.gitattributes でアセットをLFSへ振り分けます。規則を置いてから追加し、記録対象の一覧で確かめる。この順序を守ると、初回コミットの中身を自分で説明できるようになります。
共同開発では、ロックの取得から解除までを作業に含め、OFPAで分かれた関連ファイルも揃えて送ります。最後は別の作業フォルダで開き直せるかを確認し、次のギミック作りへ進みましょう。