Placing an Unreal Engine project under Git version control (properly)

Git is great, even for fully-fledged Unreal Engine projects. However, the built-in tool at the bottom right of the editor leaves a LOT to be desired. While it can place a project under version control, it does

• NOT ignore the many files that are frequently changing that should NOT be committed
• NOT use LFS for binary files, slowing regular commits down dramatically
• NOT offer any benefits besides the history display in editor (no convenient rollbacks, like UEFN does it with URC/Lore)

We can however make it work by doing a few things manually from the command line. Let me show you what they are before I forget again.

Creating the repo manually

Open the root folder of your project with your favourite command line tool. Unreal Engine doesn’t have to be closed down, but all files you’ve been working on until now should be saved. Create the repo with these two commands.

git init
git lfs install

The first initialises the current folder with an empty repo, the second makes sure LFS can be used for large binary files. Next we need to create two empty files so that Git knows what’s sage to ignore, and what needs to be committed to LFS rather than regular storage.

Create your .gitignore file and add the following contents to it:

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

Make another empty file and call it .gitattributes. This tells Git what types of files should be filtered out and stored via LFS.

*.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

That’s it! You only have to do this once. Feel free to add any other binary files to this list (like .sbsar, .blend, etc).

Make your first commit

Now we’ll place all these files and the contents of your root folder under version control. We’ll do this form the command line as well, using the following. I’d type these in line by line.

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

Depending on the size of your project, this can take a while, especially with a large number of binary files. Once it finishes you can attach a remote and push the contents to it, or keep it purely local as a “solo dev safety net”.

To make commits, you can either use the command line or your favourite Git-compatible version control tool like VS Code or GitHub for Desktop. You can optionally connect the Unreal Editor to this repo and start making commits that way, but there’s no easy roll-back support (although it is nice to see in the editor which files are version controlled or have changed thanks to little icons on the thumbnails).