Unreal Engine 4 and Git LFS

What is Git LFS?

Git Large File Storage (LFS) is an open source extension to Git that allows you easily manage large files in Git.

This is achieved by uploading the large files to a LFS store that is tied to your Git repository and then replacing those large files in your repo with a small pointer files that points to the file in LFS storage.

This allows Git to download versions of these files lazily. They are only downloaded during checkout and not when cloning or fetching. After the initial setup of Git LFS, this is all completely seamless. You can continue to use all your standard Git commands. However, these will be noticeably faster (most of the time).

Why is Git LFS?

Git repositories can typically store around 1GB if files before performance really starts to degrade. In addition, most Git hosting providers have limitations on file sizes. For example, you cannot upload a file that is larger than 100MB to GitHub.

When using Git LFS, large files are downloaded lazily: you only download versions of files referenced by commits that you are checking out. In addition, if Git can grab the files from your local LFS cache, rather than download it from the remote LFS storage, it will.

For Unreal Engine 4 projects, this can be incredibly useful. Almost of all my projects at some point have run into issues with storage. Not always just performance issues, but also max file size limitations.

For example, I recently imported some Kubold animations into one of my projects and after spinning for several minutes, the Git push command failed with an error about max file size limitations.

This prompted me to investigate Git LFS and also make some improvements to my .gitignore file, which I will share in this post.

How is Git LFS?

So how do you implement Git LFS in a Unreal Engine 4 project? Well, these days it's actually pretty simple and only takes a few minutes, depending the size of your repos and individual files.

Migrating your Unreal Engine 4 project is Git LFS can be broken down into 3 mains steps. If you're starting a new project and having committed any code to Git yet, it's even simpler.

Installing and Initializing Git LFS

There's a few different ways to install Git LFS. You can use a package manager or grab it from the project site. Some Git clients even come with it pre-installed.

I'll link to the project site, though, since it's the most universal option: https://git-lfs.github.com/.

Once you've download and installed the extension, all you need to do is initialize Git LFS for your user account by running the following:

git lfs install

This will add a .gitconfig file (if it doesn't already exist) in your home directory and will add the required configuration. You only ever have to run that command once per user.

Setting up Git LFS for a UE4 Project

The first thing you should do is make sure your .gitignore file is configured. I recommend using the "official" community UE4 .gitignore as a base. When setting up a new repo for a project in Git, you can select this from the ".gitignore" drop-down (along with a license and README.md).

You'll want to be sure to exclude any binary/generated/output files. However, do not ignore anything that you want to tracked in Git LFS.

Next, configure your .gitattributes file. This is where you'll map the file types that you want to be tracked in Git LFS.

Here's what I usually go with:

Add and commit the .gitattributes file and that's it! You're all set. Use Git just like you normally would.

Note: Free GitHub accounts get 1GB of LFS storage and 1GB of LFS bandwidth. For some project UE4 projects, you may eat through that quickly. If so, you need purchase additional storage ($5/50GB/month).

Migrating an existing UE4 Project to Git LFS

The following is only needed if you are migrating an existing UE4 project to Git LFS. You'll need to follow the steps in Setting up Git LFS in a UE4 Project first, though.

If you already have large files tracked in your Git repository, you'll need to migrate these to LFS storage. To do this, you can use the git lfs migrate command.

For example, to migrate any existing .uasset and .umap files in all local branches, you can simply run:

git lfs migrate import --everything --include="*.uasset,*.umap"

Finally, just push up your changes with a git push command.

Bonus Tip

I highly recommend setting up UE4's source control features to all you to diff and merge blueprints. This works surprisingly well and supports Git LFS.

You'll also get some nifty features, such as icons on asset thumbnails to let you know the status of said assets (changed, staged, new, etc...) and allows you to commit changes right from within the UE4 editor.