📝

【備忘録】UE5プロジェクトのGit設定まとめ

2026/01/15に公開

 これは何UE5プロジェクトをGitで管理するときに毎回調べるのが面倒なので、自分用にまとめた設定集。

 1. .gitignore — 最小構成# OS generated files
.DS_Store
Thumbs.db

# Unreal Engine
Binaries/
Build/
DerivedDataCache/
Intermediate/
Saved/
*_BuiltData.uasset

# Visual Studio
.vs/
*.sln
*.suo
*.vcxproj*
*.VC.db
*.VC.opendb

# Rider
.idea/

# Local config
*.log

 各項目メモOS系

.DS_Store → macOSが勝手に作るやつ

Thumbs.db → Windowsのサムネキャッシュ
UE5系

Binaries/ → ビルド済みバイナリ

Build/ → ビルド出力

DerivedDataCache/ → シェーダーキャッシュ等

Intermediate/ → コンパイル中間ファイル

Saved/ → ログ・オートセーブ

*_BuiltData.uasset → ライティングビルドデータ（再ビルド可能）
全部エディタ起動時に再生成されるので不要。
IDE系

.vs/ → Visual Studio設定

*.sln, *.vcxproj* → Generate Project Filesで再生成可能

*.VC.db, *.VC.opendb → Visual Studioのブラウズデータベース（巨大になりがち）

.idea/ → Rider

 ⚠️ Binaries/ を除外する際の注意Binaries/を.gitignoreに入れると、C++プロジェクトでビルド済みバイナリを共有できない。

ブループリントのみのプロジェクト → 問題なし

C++プロジェクト → チームメンバーが各自ビルドする必要あり
C++プロジェクトでビルド済みバイナリを共有したい場合はBinaries/を除外リストから外すか、リリースビルドのみ別途共有する運用を検討。

 2. .gitattributes — バイナリ判定と改行コード統一# Auto detect text files and perform LF normalization
* text=auto

# Unreal Engine files
*.uasset binary
*.umap binary
*.uproject text

# Image
*.png binary
*.jpg binary
*.jpeg binary
*.tga binary
*.exr binary
*.hdr binary

# Audio
*.wav binary
*.mp3 binary
*.ogg binary

# Fonts
*.ttf binary
*.otf binary

# FBX/Alembic
*.fbx binary
*.abc binary

 3. GitHub無料枠で収める — LFSは使わない結論：個人開発・小規模チームはLFSを使わず、普通のGitで1GB以内を目指す。

 GitHub無料枠の制限

項目
制限


リポジトリサイズ
推奨1GB、上限5GB

単一ファイル
100MB以上はプッシュ拒否

LFSストレージ
10GiB

LFS帯域
10GiB/月

以前は1GBだったが、現在は10GiBに増量されている。中規模プロジェクトならLFSも選択肢に入る。

 LFSを使うべきケース

条件
判断


個人開発・小規模（1GB以内）
LFSなしでOK

中規模（1〜10GB）
LFS検討の余地あり

大規模・チーム開発
LFS有料プランか自前サーバー

企業
Perforce推奨

ただし、LFSは管理が複雑になる。clone時にgit lfs installが必要、帯域超過時の課金リスクなど。迷ったら普通のGitで1GB以内を目指すのが無難。

 1GBに収めるチェックリスト□ Starter Content 使わない / 削除済み
□ Marketplace / ThirdParty アセットは .gitignore で除外
□ Migrated/ フォルダは .gitignore で除外
□ ソースファイル（.psd, .blend, .fbx原本）は別管理
□ テクスチャは2K以下（4Kは本当に必要な箇所だけ）
□ 動画・音声ファイルは Content/ に入れない
□ 未使用アセット削除済み（サイズマップで確認）
□ リダイレクタ修正済み

 テクスチャが容量の大半UE5プロジェクトの肥大化原因の8割はテクスチャ。


解像度
1枚あたり目安


4K (4096x4096)
20〜60MB

2K (2048x2048)
5〜15MB

1K (1024x1024)
1〜4MB

対策：
VFXや背景は1K〜2Kで十分
4Kはヒーローアセット（主人公など）だけ
インポート時に Maximum Texture Size を設定

 未使用アセットの確認方法サイズマップ で容量食ってるアセットを可視化：

ウィンドウ > 開発者ツール > サイズマップ
アセット監査 で参照されてないアセットを特定：

ウィンドウ > 開発者ツール > アセット監査

 現在のリポジトリサイズ確認# ローカル
du -sh .git

# リモート（GitHub CLI）
gh repo view --json diskUsage
500MB超えたら黄色信号、800MB超えたら整理必須。

 追加の .gitignore（容量削減用）# 外部アセット
Content/Marketplace/
Content/ThirdParty/
Content/Migrated/

# メディア
Content/Movies/
Content/Audio/Music/
*.mp4
*.mov
*.wav

# ソースファイル
*.psd
*.blend
*.blend1
*.max
*.ma
*.mb
*.zpr
*.ztl

 ⚠️ *.ubulk を除外する場合の注意*.ubulkはテクスチャストリーミング用の分割データ。除外すると：
ストリーミングテクスチャが正常に読み込めない可能性あり
パッケージビルドで問題が起きることも
推奨：開発中は除外せず、容量がどうしても厳しい場合のみ検討。除外する場合はテスト必須。

 個人開発の現実的な構成プロジェクトルート/
├── .git/                  ← Gitで管理（目標1GB以内）
├── Content/
│   ├── Blueprints/        ✓ コミット
│   ├── Maps/              ✓ コミット
│   ├── Materials/         ✓ コミット
│   ├── Textures/          ✓ コミット（2K以下）
│   ├── VFX/               ✓ コミット
│   ├── Marketplace/       ✗ .gitignore
│   ├── Migrated/          ✗ .gitignore
│   └── Movies/            ✗ .gitignore
├── SourceAssets/          ← Git管理外（Google Driveなど）
│   ├── PSD/
│   ├── Blender/
│   └── Substance/
└── Config/                ✓ コミット

 4. UE5エディタ内Git連携 — エディタからコミットUE5エディタ内でGit操作が可能。

 設定方法編集 > エディタの環境設定 > ソースコントロール
プロバイダーを Git に変更

リポジトリを初期化 または既存リポジトリを認識

 できることアセットのチェックアウト状態表示
コンテンツブラウザから直接コミット
変更履歴の確認

 注意点複雑な操作（ブランチ切り替え、マージ）はターミナル推奨

.uassetの差分は見れない（バイナリなので）

 5. ブランチ戦略 — シンプルに保つ
 個人開発main一本でOK。ブランチ切る必要なし。

 小規模チーム（2〜5人）main           ← 常に動作する状態
  └── feature/ ← 機能追加時に切る
# 機能ブランチ作成
git checkout -b feature/new-vfx

# 作業完了後
git checkout main
git merge feature/new-vfx
git branch -d feature/new-vfx

 大規模チームGit + ブランチ戦略では限界がある。Perforce + ストリーム構成を検討。

 6. 現場で使うテクニック
 One File Per Actor (OFPA) — レベル競合回避の必須設定レベルが1つの巨大な.umapではなく、アクター単位のExternal Actorsに分割される。複数人で同じレベル触っても競合しにくくなる。
有効化方法：

World Partition使用時 → 自動で有効（デフォルトON）

非World Partition → ウィンドウ > ワールドセッティング > Use External Actors にチェック

 ⚠️ OFPA + Gitの制限OFPAで生成されるファイル名はエンコードされた形式（例：YOURMAP__ExternalActors__Actor_12345.uasset）になる。

Perforce → エディタ内からChangelist管理が可能

Git → エディタ内からのファイル追跡が制限される。ターミナルでのgit statusやGitクライアントでの確認が必要
公式ドキュメントより：
"Changelist support is only available when using Perforce as your source control provider."
Gitでも機能自体は使えるが、どのアクターがどのファイルに対応しているかの確認がPerforceより不便。

 World Partition（UE5.1以降）オープンワールド向けだが、レベル分割にも有効。

ワールド設定 > World Partition > Enable で有効化。

 バイナリ競合の運用ルール.uassetはマージ不可。Gitでは「誰が今どのアセット触ってるか」を共有する仕組みがない。
対策1: Slackやスプレッドシートで編集中アセットを宣言

対策2: 機能単位でフォルダを分け、担当者以外は触らない

対策3: 本気でやるならPerforce（業界標準）に移行

 shallow clone — clone高速化git clone --depth 1 https://github.com/xxx/repo.git
履歴が要らないなら--depth 1で最新だけ取得。数十GB→数GBになることも。

 git gc — 定期メンテナンスgit gc --aggressive --prune=now
月1くらいでやると良い。

 pre-commit hook — 100MB超えコミット防止.git/hooks/pre-commitを作成：
#!/bin/bash
max_size=100000000  # 100MB

files=$(git diff --cached --name-only)
for file in $files; do
  if [ -f "$file" ]; then
    # macOS/Linux両対応
    if [[ "$OSTYPE" == "darwin"* ]]; then
      size=$(stat -f%z "$file")
    else
      size=$(stat -c%s "$file")
    fi
    if [ "$size" -gt "$max_size" ]; then
      echo "Error: $file is larger than 100MB (${size} bytes)"
      exit 1
    fi
  fi
done
chmod +x .git/hooks/pre-commit

 DDC共有 — シェーダーコンパイル地獄を回避チーム開発で共有フォルダにDDCを置く。
DefaultEngine.iniに追記：
Windows（UNCパス）
[DerivedDataBackendGraph]
Shared=(Type=FileSystem, ReadOnly=false, Clean=false, Flush=false, DeleteUnused=true, UnusedFileAge=10, FoldersToClean=10, MaxFileChecksPerSec=1, Path="\\server\share\UE-DDC", EnvPathOverride=UE_SHARED_DDC_PATH)
macOS/Linux（NFSマウント等）
[DerivedDataBackendGraph]
Shared=(Type=FileSystem, ReadOnly=false, Clean=false, Flush=false, DeleteUnused=true, UnusedFileAge=10, FoldersToClean=10, MaxFileChecksPerSec=1, Path="/Volumes/shared/UE-DDC", EnvPathOverride=UE_SHARED_DDC_PATH)
初回以降、他メンバーがビルドしたシェーダーを再利用できる。

 アセット命名規則

プレフィックス
種類


SM_
Static Mesh

SK_
Skeletal Mesh

T_
Texture

M_
Material

MI_
Material Instance

BP_
Blueprint

NS_
Niagara System

NE_
Niagara Emitter

ABP_
Animation Blueprint

WBP_
Widget Blueprint


 リダイレクタを放置しないアセット移動するとRedirectorが残る。放置すると参照がゴチャゴチャになる。
移動後に コンテンツブラウザ > 右クリック > リダイレクタを修正 で解消。

 .gitconfig 高速化git config --global core.preloadindex true
git config --global core.fscache true
git config --global gc.auto 256
Windowsで特に効果あり。

 7. よくあるトラブルと対処法
 100MBファイルをpushしようとして失敗remote: error: File xxx.uasset is 150.00 MB; this exceeds GitHub's file size limit of 100.00 MB
対処法1: コミット前なら.gitignoreに追加して除外
対処法2: 直前のコミットに含まれている場合
# 直前のコミットを取り消し（変更は残る）
git reset --soft HEAD~1

# 問題のファイルを除外
echo "path/to/large-file.uasset" >> .gitignore
git add .gitignore

# 再コミット
git add -A
git commit -m "Remove large file"
対処法3: 複数コミット前に入れてしまった場合
# BFG Repo-Cleanerで履歴から削除
bfg --strip-blobs-bigger-than 100M
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force
⚠️ --force pushは履歴を書き換えるので、チーム開発では要相談。

 リモートとローカルの履歴が divergedhint: Updates were rejected because the tip of your current branch is behind
# リモートの変更を取り込んでからpush
git pull --rebase
git push

 .uassetの競合が発生バイナリファイルはマージできない。どちらかを選ぶしかない。
# 自分の変更を採用
git checkout --ours path/to/file.uasset

# 相手の変更を採用
git checkout --theirs path/to/file.uasset

git add path/to/file.uasset
git commit -m "Resolve conflict"

 8. マーケットプレイスアセットの扱い方針1: .gitignoreで除外し、READMEに「〇〇アセット必要」と書く

方針2: Git Submoduleで別リポジトリ管理

方針3: 必要な部分だけMigrateして使う
チーム開発なら方針1が楽。ライセンス的にも再配布しないほうが安全。

 9. グローバル .gitignore — PC全体に適用毎回.DS_Store書くのが面倒なら、グローバル設定。
git config --global core.excludesfile ~/.gitignore_global
~/.gitignore_globalを作成：
.DS_Store
Thumbs.db
*.VC.db
*.VC.opendb

 10. 既にコミットしちゃった場合git rm --cached .DS_Store
git rm --cached -r Intermediate/
git commit -m "Remove ignored files"

 おまけ：新規プロジェクト作成時のコマンドcd /path/to/project
git init

# .gitignore作成（この記事の内容をコピペ）
# .gitattributes作成（この記事の内容をコピペ）

git add -A
git commit -m "Initial commit"

# GitHubで先にリポジトリ作成しておく
git remote add origin https://github.com/username/repo.git
git push -u origin main

 参考
 GitHub公式
リポジトリの制限 - サイズ制限の詳細

大きなファイルについて - 50MB警告、100MB上限
Git LFSについて

 UE5公式
ソース管理 - エディタ内でのGit/Perforce連携

One File Per Actor - レベル競合回避の必須機能

World Partition - 大規模レベル管理

 ツール
github/gitignore - UnrealEngine.gitignore - 公式テンプレート

github/git-sizer - リポジトリ肥大化分析

BFG Repo-Cleaner - 履歴から大きいファイル削除

項目	制限
リポジトリサイズ	推奨1GB、上限5GB
単一ファイル	100MB以上はプッシュ拒否
LFSストレージ	10GiB
LFS帯域	10GiB/月

条件	判断
個人開発・小規模（1GB以内）	LFSなしでOK
中規模（1〜10GB）	LFS検討の余地あり
大規模・チーム開発	LFS有料プランか自前サーバー
企業	Perforce推奨

解像度	1枚あたり目安
4K (4096x4096)	20〜60MB
2K (2048x2048)	5〜15MB
1K (1024x1024)	1〜4MB

プレフィックス	種類
`SM_`	Static Mesh
`SK_`	Skeletal Mesh
`T_`	Texture
`M_`	Material
`MI_`	Material Instance
`BP_`	Blueprint
`NS_`	Niagara System
`NE_`	Niagara Emitter
`ABP_`	Animation Blueprint
`WBP_`	Widget Blueprint

GitHubで編集を提案

これは何

1. .gitignore — 最小構成

各項目メモ

⚠️ Binaries/ を除外する際の注意

2. .gitattributes — バイナリ判定と改行コード統一

3. GitHub無料枠で収める — LFSは使わない

GitHub無料枠の制限

LFSを使うべきケース

1GBに収めるチェックリスト

テクスチャが容量の大半

未使用アセットの確認方法

現在のリポジトリサイズ確認

追加の .gitignore（容量削減用）

⚠️ *.ubulk を除外する場合の注意

個人開発の現実的な構成

4. UE5エディタ内Git連携 — エディタからコミット

設定方法

できること

注意点

5. ブランチ戦略 — シンプルに保つ

個人開発

小規模チーム（2〜5人）

大規模チーム

6. 現場で使うテクニック

One File Per Actor (OFPA) — レベル競合回避の必須設定

⚠️ OFPA + Gitの制限

World Partition（UE5.1以降）

バイナリ競合の運用ルール

shallow clone — clone高速化

git gc — 定期メンテナンス

pre-commit hook — 100MB超えコミット防止

DDC共有 — シェーダーコンパイル地獄を回避

アセット命名規則

リダイレクタを放置しない

.gitconfig 高速化

7. よくあるトラブルと対処法

100MBファイルをpushしようとして失敗

リモートとローカルの履歴が diverged

.uassetの競合が発生

8. マーケットプレイスアセットの扱い

9. グローバル .gitignore — PC全体に適用

10. 既にコミットしちゃった場合

おまけ：新規プロジェクト作成時のコマンド

参考

GitHub公式

UE5公式

ツール

Discussion