Managing UE Projects Safely with Git: .gitignore, LFS, and One File Per Actor

You've started building a game in UE and it's time to back it up. Maybe you want to work on it with a friend. You've heard Git is the answer, so you run git add . on the whole project folder and commit. The result is a multi-gigabyte commit, and by the next day the history has ballooned past the point of recovery.

UE projects are different from most other projects because the assets are binary and enormous. A single level running into hundreds of megabytes is normal. Drop that into Git without a plan and it falls apart fast. This article covers the three pillars of managing a UE project safely in Git: which folders to exclude, Git LFS, and locking. At the end, we'll make a first commit with everything set up correctly.

What You'll Learn

• Folders you must never commit (Saved / Intermediate / DerivedDataCache / Binaries)
• Why .uasset files need Git LFS
• Binaries can't be merged, so you protect them with locks
• How One File Per Actor reduces conflicts on a team
• Hands-on: making a correct first commit on a new project

---

Folders You Must Never Commit

A UE project folder mixes things you made with things the engine generated. Only the former belongs in Git.

Auto-generated folders should never be committed. They waste space, and because their contents differ from machine to machine, they cause conflicts in collaborative work.

Here are the four main folders to exclude:

• Saved: Autosaves, logs, and temp files. Changes every time you run the game.
• Intermediate: Intermediate build files. Regenerated on demand.
• DerivedDataCache (DDC): Shader and other caches. Huge and machine-specific.
• Binaries: Compiled executables. Rebuilt from source.

Excluding these is the job of .gitignore. You don't have to write it yourself. When you create a new repository on GitHub, pick UnrealEngine from the .gitignore template list and everything above is excluded from the start. If you'd rather prepare it locally, grab UnrealEngine.gitignore from GitHub's github/gitignore repository and drop it in your project root as .gitignore. What you do commit is Content (the assets themselves), Config, Source (C++), the .uproject file, and any Plugins folder you wrote yourself.

Why You Need Git LFS

Even after .gitignore removes the generated files, one problem remains: the assets themselves (.uasset / .umap) are binary.

Git is fundamentally a tool for tracking text differences. It's great at recording "line 3 changed here" in source code. But .uasset is binary, so even a tiny edit makes the whole file look like something entirely new. Every time you edit an asset, an entire copy of the file piles up in your history.

Git LFS (Large File Storage) solves this. LFS pulls large binaries out of the history itself and stores them elsewhere. The history keeps only a small pointer saying "this file lives over there," which keeps the repository itself lightweight.

You declare which files go on LFS in .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 and .umap are mandatory. Beyond those, put source FBX files, audio, and large images on LFS as well: anything binary and sizable.

---

Binaries Can't Be Merged

There's one thing Git LFS can't solve for you: binaries can't be merged.

With text, Git can automatically merge two people's edits as long as they touched different lines. But .uasset is binary, so when two people edit the same asset, Git has no way to tell which version is correct and one of them has to be overwritten. Someone's work disappears entirely.

File locking is what prevents this. When someone runs git lfs lock on an asset before editing it, nobody else can edit that file. Think of it as putting up a sign that says "I'm working on this map right now." Once the work is pushed, the lock is released. If you plan to rely on locking seriously, add a lockable attribute in .gitattributes (for example *.uasset lockable) so that editing without a lock triggers a warning.

UE5 also has a feature that reduces conflicts in the first place: One File Per Actor (OFPA). With World Partition enabled, each Actor placed in a level is saved as its own file. Instead of everyone fighting over one giant .umap, the level splits into per-Actor files, so as long as you're working on different Actors you never collide.

---

Hands-On: A Correct First Commit

Regardless of project size or genre, this is the one-time setup everyone does at the start. Getting it right here determines how the rest of the project goes.

We'll take a new project (a template or your own) and make a first commit with the correct settings.

Here's what you'll see. Set up .gitignore and LFS before committing, and a project that would have been several gigabytes becomes a light commit of a few tens of megabytes.

Steps

First, install Git and Git LFS themselves (LFS is a separate tool from Git) and set user.name and user.email with git config. Once that's done, run the following in your project's root folder (where the .uproject lives), in this order.

# 1. Initialize the repository
git init

# 2. Enable Git LFS in this repository (LFS itself must already be installed)
git lfs install

# 3. Place .gitignore and .gitattributes in the root
#    .gitignore     ... excludes Saved/ Intermediate/ DerivedDataCache/ Binaries/ etc.
#    .gitattributes ... registers *.uasset *.umap etc. with filter=lfs

# 4. Commit .gitattributes first (this locks in what LFS covers)
git add .gitattributes .gitignore
git commit -m "Add gitignore and LFS attributes"

# 5. Commit everything else
git add .
git commit -m "Initial commit"

The order matters. Placing .gitattributes before you run git add . is what puts .uasset files on LFS from the very first commit. If you commit assets before the settings exist, they bypass LFS and land directly in the history, which is a pain to undo later.

Verify

Once the commit is done, check it with two commands.

• Run git status and confirm that Saved/ and Intermediate/ don't appear. If they do, .gitignore isn't taking effect.
• Run git lfs ls-files and confirm that your .uasset files are listed. If they aren't, you committed before placing .gitattributes.

If both match expectations, your setup worked. If the assets didn't end up on LFS, the simplest fix is to redo these steps while the repo is still private to you.

Two things to take away.

• Place the config files first: .gitignore and .gitattributes must exist before you commit any assets. Reverse the order and large binaries get burned into the history where you can't remove them.
• No generated files, all assets on LFS: stick to these two and the repository stays light. git status and git lfs ls-files make it easy to confirm every time.

With the first commit behind you, you can build on top of it with confidence, whether that's packaging or day-to-day development.

Bonus: Good to Know for Later

You can move to LFS after the fact. Even if you've already committed .uasset files normally, you can move past history onto LFS with something like git lfs migrate import --include="*.uasset,*.umap". It rewrites history, though, so do it before sharing the repo with anyone.

A local commit is not a backup. git commit only writes a record onto your own PC. If that PC dies, so does your work. It becomes a backup only once you create a remote on GitHub or similar and run git push. For collaboration, everyone installs Git LFS locally and shares assets through an LFS-capable remote.

Big files never really leave. Git preserves history, so a large binary you add and later delete stays in the history forever, and that weight follows every clone. Not adding it in the first place is the best defense.

Larger teams may want Perforce. Studios where many people edit binaries heavily often pick Perforce or Diversion, where locking is standard. For solo or small-team development, though, Git plus LFS works fine. Start with Git and consider alternatives only if you hit a wall.

Summary

Git management for UE projects comes down to getting the initial setup right. Exclude the generated folders with .gitignore, put .uasset on LFS via .gitattributes, and place both files before any assets. On a team, remember that binaries can't be merged, so avoid conflicts with locking and OFPA. Cover those points and your repository stays small and your history stays clean.

Take a look at your own project right now. Does git status list Saved/ or Intermediate/? It's worth checking.