Setting Up an Unreal Engine Project for Version Control (Git + LFS)

Unreal Engine’s built-in “Add revision control” Git option sets things up badly: no LFS, no proper ignore file. Here’s the manual setup that works — quick reference style. Do this once, outside the editor, before your first commit.

Step 1: Install Git and Git LFS

Grab Git from git-scm.com and LFS from git-lfs.com if it’s not included. Then, once per machine:

git lfs install

Step 2: Initialise the repository

In the project root (the folder with the .uproject file):

git init

Don’t add or commit anything yet — the order of the next steps matters.

Step 3: Create the .gitignore

Binaries/
DerivedDataCache/
Intermediate/
Saved/
.vs/
*.sln

These folders are regenerated by the engine. What stays under version control: Content/, Config/, Source/ and the .uproject file.

Step 4: Create the .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
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text

Add any other binary formats you keep in the project (.tga, .exr, .mp4, …) following the same pattern.

Step 5: Commit in the right order

LFS tracking only applies to files added after the .gitattributes rules exist, so commit the config files first:

git add .gitignore .gitattributes
git commit -m "VCS configuration"
git add .
git commit -m "Initial project state"

Step 6: Verify LFS is working

git lfs ls-files

Your .uasset files should appear in the list. If they don’t, check the .gitattributes before going any further.

Fixing an existing project with a broken Git history

If the project was previously committed without LFS: delete the hidden .git folder in the project root and start fresh with the steps above.

Daily workflow notes

• File → Save All in the Unreal editor before every commit — Git only sees what’s on disk.
• Commit at every working state, with messages that describe the state (“Added enemy patrol AI, working”).
• Any Git frontend works against the same repo: command line, VS Code, GitHub Desktop, Fork. Avoid the Unreal editor’s own Git plugin for anything beyond trivial check-ins — it’s still beta.
• .uasset diffs only show “file changed” — they’re binary. That’s expected.
• No remote needed for local rollback insurance; a bare repo on a second drive adds cheap safety.

Remote and Collaboration Issues

While this workflow is great for solo devs on their local system, Git isn’t great for working with a remote, or as part of a team. Here’s why: repo sizes can easily climb to 100GB and more due to large binary files in Unreal projects. GitHub will issue a polite warning when your repo grows to over 2GB. While you may still be able to upload more data, you’ll likely get throttled.

Furthermore, there’s no way to tell a team mate that a file is locked while you’re working on it. This wouldn’t be a problem with plain text files because they could be diffed on merge, but most .uasset files are binaries so it means you’ll inevitably invite file conflicts into your life.

If you use your own ground-truth Git hosting solution (i.e. local or remote file server via SSH, Samba or http), LFS won’t for file transfers out of the box. You can disable it, but your commits will take forever to sync with the remote.

Bottom line: Git isn’t great for Unreal Engine collaboration, but it’s a good safety net when you work on local projects and want a roll-back option.

Alternatives

Once a team is involved, remember that .uasset files can’t be merged. Options at that point: Perforce Helix Core (free for up to 5 users, exclusive checkout), Diversion (version control built specifically for Unreal Engine — free on FAB with an optional Pro plan, supports UE 5.3+), or Anchorpoint (a Git-based GUI with locking).

Also keep an eye on Lore, Epic’s new open-source version control system announced at State of Unreal 2026 — binary-first by design, already documented for UE 5.8, and likely to become the native choice for UE projects as it matures. See Lore.org.