Unreal Engine source control: Perforce vs Git LFS, and how to choose

Why source control for Unreal Engine is different

Source control keeps every version of a project and lets a team work on it at the same time. For ordinary software that is a solved problem: files are text, they are small, and two people who edit the same file get their lines merged. Game development breaks all three assumptions, whatever the engine, and an Unreal Engine project breaks them more than most.

• Most of the project is binary. Meshes, materials, Blueprints and levels are .uasset and .umap files. They cannot be read as text and cannot be compared line by line.
• Binary assets cannot be merged. If two people change the same Blueprint, one of the two versions has to be thrown away. The only protection is to make sure one person edits each asset at a time, which means locking.
• The project is large and grows fast. Textures, audio and levels reach gigabytes, and every saved version is a new copy. A system that hands every version of every file to every machine stops being usable.
• Half the team does not write code. Artists, level designers and animators change more files than programmers do, and they have no reason to learn a command line first.

So the question for a game team is narrower than "which version control system is best". It is: which system stores large binary files well, enforces locks on them, and can be used every day by people who are not engineers. Two systems cover almost every Unreal team: Perforce, and Git with the Git LFS extension.

Perforce vs Git LFS for Unreal Engine: which one to choose

Both systems run shipped Unreal games. They start from different models, and the differences below follow from the model, not from the quality of either tool.

Licensing and hosting costs differ between the two and change over time, so compare the current terms of Perforce and of your Git host for your team size and storage instead of relying on an old comparison.

Perforce usually fits when

• Most of the daily changes are binary content made by artists and designers.
• The project is content-heavy and will keep growing for years.
• You want the server to refuse a second edit on a locked asset, with no discipline required from the team.
• People need only a part of the project on their disk.
• Someone in the studio can look after a server, or you use a hosted one.

Git LFS usually fits when

• The team is small and mostly programmers who already work in Git.
• The project is code-heavy, with a modest amount of binary content.
• You already have a Git host, reviews and build pipelines you want to keep.
• Your host supports LFS locking and the team is willing to lock before editing.

If the answers point both ways, let the binary content decide: it is the part of the project that neither system can merge for you, and the part that grows.

They are not the only options. The editor also ships providers for Subversion and for Unity Version Control (formerly Plastic SCM), and newer hosted services such as Diversion exist. Perforce and Git LFS are the two this guide covers because they are the two most Unreal teams end up choosing between.

How to choose and set up source control for an Unreal project

Decide before the first asset is committed. Moving a project from one system to the other later is possible, but it costs history, time and a freeze for the whole team.

1. 1

   Answer three questions about your team

   • Who changes the most files? If it is artists and designers working on binary content, enforced locking matters more than branching.
   • How large will the project get? A code-heavy prototype and a content-heavy production put very different loads on the system.
   • What does the team already know and run? An existing Git host with build pipelines, or an existing Perforce server, is a real cost to walk away from.
2. 2

   Choose Perforce or Git LFS

   Hold your three answers against the comparison and the two lists above. Write the decision down together with the reason: in a year someone will ask why, and "we already had it" is a legitimate answer.

3. 3

   Set up locking before the first asset

   On Perforce, give .uasset and .umap the exclusive checkout file type through the server typemap, so checking a file out is what locks it. See Perforce typemap for Unreal Engine. On Git, commit a .gitattributes that sends those files to LFS and marks them lockable, and check that your host supports the LFS locking API. See Git LFS for Unreal Engine.

   Important:Both settings apply to files added afterwards. Assets committed before the rule existed keep their old type, and fixing them later means re-typing files on Perforce or rewriting history on Git.
4. 4

   Keep generated folders out

   Unreal rebuilds Intermediate/, Saved/ and DerivedDataCache/ on every machine. Exclude them from the start, with .p4ignore on Perforce or .gitignore on Git. Decide on Binaries/ as a team: leave it out when everyone compiles locally, keep it when artists need the editor binaries without building them.

5. 5

   Connect the Unreal Editor

   The editor can talk to your source control system directly: it checks assets out when you edit them, shows their state in the Content Browser and submits from inside the editor. Epic documents the Perforce setup in Using Perforce as Source Control for Unreal Engine. Set it up on one machine first, then write down the settings for the rest of the team.

6. 6

   Walk the non-programmers through one full day

   Source control fails when part of the team works around it. Sit with an artist for one loop: get the latest version, take the asset, save, publish. On Perforce that loop is described in Perforce for artists and designers.

Common source control mistakes in Unreal projects

• Committing generated folders. Intermediate/, Saved/ and DerivedDataCache/ are rebuilt on every machine. In the repository they only add size and conflicts.
• Adding assets before locking is configured. The first weeks of content end up with the wrong file type, and two people overwrite each other before anyone notices.
• Using plain Git for content. Without LFS, every version of every asset is in every clone, and cloning the project soon takes hours.
• Making files writable instead of checking them out. The edit happens behind the server, without the lock that protects it.
• Holding a lock for days. Nobody else can work on that asset. Release what you are not changing.
• Leaving the artists out. If only programmers use source control, the content, which is most of the game, has no history and no backup.

Where Gameheim fits: Perforce and Git from the browser

Gameheim does not replace your source control system. It sits on top of the one you chose and puts the daily operations in a browser page that the whole team can use, next to the tasks and bugs of the same project. A project uses one system 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: see move a project from Perforce to Git.

• On Perforce, the P4 Workspace page covers sync, check out, lock, reconcile, shelve and submit. A submit can be linked to the tasks it completes, the Lock Dashboard shows the whole team who holds which asset, and locks held for more than 24 hours are marked stale and the holder is reminded. This is the more complete integration.
• On Git, the Git Workspace page covers clone, fetch, pull, push, stage, commit, branches, history and the patterns tracked by LFS. Git support is experimental: locking a file is still git lfs lock, and diffs and conflicts are handled with Git itself.
• Everything above source control (tasks, bugs, wiki, capacity, roles) works the same way on both.

In both cases the commands run on your own computer through the Gameheim Agent, with your own account. The browser sends a request, the agent runs the command against your server or Git host, and the result comes back to the page. File contents travel between your machine and your server, not through Gameheim.

It does not compete with the editor integration either: a file checked out in Gameheim is checked out in Perforce, and a submit from Gameheim is a normal submit that shows up in every other tool your studio uses. You can keep checking assets out from the editor while you work, and use the browser for syncing, reviewing what changed, team locks and submitting with the task attached.

Connecting a project

1. Create a project and set System to the one you chose. See Getting started with Gameheim.
2. Each person installs the Gameheim Agent once. See Install the Gameheim Agent.
3. On Perforce, save your account with P4 Credentials and choose or create a workspace with Manage Workspace (Perforce workspace setup for Unreal Engine). On Git, enter your token in Git credentials and click Configure & clone (Git LFS for Unreal Engine).

Frequently asked questions