Git LFS for Unreal Engine: setup, .gitattributes and locking

Why Unreal Engine projects need Git LFS

Git is built around text: every clone carries the full history of every file. That model is excellent for code and a heavy load for an Unreal project, where most of the repository is binary content (.uasset, .umap, textures, audio) that changes often and cannot be diffed. Without help, every version of every asset ends up in every clone, and the repository grows until cloning it takes hours.

Git LFS (Large File Storage) fixes the size problem: it replaces large files with small text pointers inside Git and stores the real content on an LFS server, downloading only the versions you check out. Which files go to LFS is decided by patterns in .gitattributes.

LFS alone does not fix the second problem: Unreal assets cannot be merged. If two people change the same Blueprint on two branches, one of the two versions has to be thrown away. Git LFS answers that with file locking: files marked lockable are checked out read-only, and you take a lock on the server before editing. It only works if the remote supports the LFS locking API and the team actually uses it.

How Gameheim runs Git and Git LFS projects (experimental)

Gameheim's version-control layer works with Perforce and with Git. A project uses one or the other, chosen when it is created: System offers Perforce (Helix Core) and Git + Git LFS (the Git option appears only where Git is available on the server). A Perforce project can later move to Git, and back, with a guided transition that keeps its tasks, bugs and history in Gameheim: see move a project from Perforce to Git. Everything above version control (tasks, bugs, wiki, capacity, roles) works the same either way.

Git support is experimental. The daily loop works end to end from the browser; Perforce is the more complete integration today, and large LFS transfers are still being hardened.

What the Git Workspace does

• Configure & clone: the Gameheim agent clones the remote into a folder you choose on your machine. LFS content is downloaded as files are checked out.
• Refresh, Fetch, Pull and Push from the toolbar.
• Changes tab: files grouped as Conflicts, Staged, Changes and Untracked, with Stage, Unstage and Discard, and Commit or Commit & Push with a message.
• Branches tab: switch branch, Create branch.
• History tab: the last 50 commits with author and date.
• LFS tab: the patterns your .gitattributes sends to LFS, read from the repository, so you can see what is stored as a pointer.

Commands run on your computer through the agent, with your own credentials: file contents go between your machine and your Git host, not through Gameheim. Your personal access token is stored encrypted and delivered only to your agent.

What it does not do yet

• LFS file locking is not operated from Gameheim. The project records whether the remote supports LFS locking, and the LFS tab tells you when it does not; to lock and unlock, use git lfs lock and git lfs unlock or a Git client that supports them.
• Adding LFS patterns, viewing diffs and resolving merge conflicts are done outside Gameheim. Conflicted files are listed; resolve them on disk, then stage them.
• SSH keys are not supported yet: authentication uses a personal access token over HTTPS.

How to set up a Git LFS project in Gameheim

1. 1

   Create the project with Git

   Create a project and set System to Git + Git LFS. In Git repository, choose Hosting (Managed provider or Self-hosted server), the Provider (GitHub, GitLab, Azure DevOps, Gitea, Bitbucket or Other), the Remote URL and the Default branch. Fill LFS endpoint only if your LFS server is not at the default address, and tick Remote supports LFS file locking if it does.

2. 2

   Enter your Git credentials

   Open Git Workspace and click Git credentials. Paste the token into Personal Access Token; Username (optional) depends on the host (GitHub accepts any non-empty value, Azure DevOps ignores it, some GitLab setups need your account name). Click Test Connection, then Save.

   Tip:Your agent picks up a new token at its next project sync, within five minutes, or immediately if you restart it. If your organization has a rotation policy, the modal tells you when the stored token has to be entered again.
3. 3

   Clone with the agent

   Click Configure & clone and enter the local folder for the clone. The button works only while your agent is online. A large repository with many LFS objects can take a long time; the page shows Working… until it finishes.

4. 4

   Work through the daily loop

   Click Pull before you start. On Changes, Stage what belongs together, write a message and click Commit & Push (or Commit and Push later). The branch badge shows how many commits you are ahead of or behind the remote.

5. 5

   Check what LFS tracks

   Open the LFS tab. If .uasset or .umap is missing from the list, those files are going into plain Git: fix .gitattributes before committing more content.

A .gitattributes for Unreal Engine with Git LFS

Each line maps a pattern to LFS. -text stops Git from touching line endings, and lockable makes the file read-only on checkout until you lock it. Add patterns for any other large formats your studio uses.

# Unreal assets: stored in LFS, never merged, lockable
*.uasset filter=lfs diff=lfs merge=lfs -text lockable
*.umap filter=lfs diff=lfs merge=lfs -text lockable

# Source art and media: stored in LFS
*.fbx filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.tga filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.exr filter=lfs diff=lfs merge=lfs -text
*.hdr filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text
*.ogg filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text

# Only if you commit editor binaries (see .gitignore)
*.dll filter=lfs diff=lfs merge=lfs -text
*.exe filter=lfs diff=lfs merge=lfs -text
*.pdb filter=lfs diff=lfs merge=lfs -text

Commit .gitattributes on its own, before any asset, and check the result with git lfs ls-files: every .uasset and .umap you commit afterwards should appear in that list.

Generated folders should not be committed at all. A starting .gitignore for an Unreal project (keep Binaries/ if team members who do not compile need the editor binaries):

# Generated by Unreal Engine: rebuilt on every machine
Binaries/
DerivedDataCache/
Intermediate/
Saved/
Plugins/*/Binaries/
Plugins/*/Intermediate/

# IDE files
.vs/
.vscode/
.idea/
*.sln

Git LFS file locking for .uasset and .umap

Locking is what makes binary work safe in Git. The commands below come from the Git LFS file locking guide. Locks are held on the server, so they work across branches only as long as everyone locks before editing.

# once per machine
git lfs install

# track Unreal assets (writes .gitattributes)
git lfs track --lockable "*.uasset" "*.umap"
git add .gitattributes

# check which files are stored in LFS
git lfs ls-files

# lock before editing, unlock after pushing
git lfs lock Content/Maps/Level01.umap
git lfs locks
git lfs unlock Content/Maps/Level01.umap

• A lockable file is read-only until you lock it. If an editor saves anyway, the save fails, which is the point.
• git lfs locks shows who holds which file. An administrator can remove someone else's lock with git lfs unlock --force.
• Not every host implements the LFS locking API. Check your host's documentation, and record the answer on the project with Remote supports LFS file locking.

The daily Git LFS loop for an Unreal project

With .gitattributes in place, LFS works inside the normal Git commands. Each person runs git lfs install once, so the LFS hooks are set up before the first clone; after that, clone, pull, commit and push move the LFS content along with the pointers.

# first time: LFS hooks, then clone (LFS content comes with the checkout)
git lfs install
git clone https://git.example.com/studio/MyGame.git

# every day
git pull
git add Content/Maps/Level01.umap
git commit -m "Level01: new lighting pass"
git push

Stage assets deliberately rather than with git add .: renaming or moving an asset in the editor also changes the assets that reference it and can leave redirectors behind, and a stray .uasset in a commit is a conflict waiting to happen for whoever edits it next. Pull before starting work on a binary asset, lock it, and push soon after.

Troubleshooting Git LFS in Unreal projects

• Assets open as tiny text files or Unreal says the package is corrupt. You have LFS pointers instead of content: LFS was not installed when the repository was cloned. Run git lfs install and git lfs pull.
• The repository is huge although LFS is set up. Assets were committed before the pattern existed. git lfs migrate import --include="*.uasset,*.umap" rewrites history to move them; coordinate it with the whole team.
• Test Connection fails in Gameheim. Check that the token has read and write access to this repository and has not expired, and that the Remote URL uses HTTPS.
• Configure & clone is disabled. The agent is offline or not installed; the page says which.
• Pull stops with conflicts. Resolve the listed files on disk (for binary assets, pick one version), then Stage them and commit.

Frequently asked questions