Rohan Mayya

Definitive guide to Git for Unreal Engine

We have an Unreal Engine repo that’s well over 300gb (and will scale to 600+ when done) at this point, and we manage it all with Git. We avoid Perforce because the team is familiar with Git, and Perforce is prohibitively expensive (and overly corporate-y).

The main problem we wrangled through for days is to think about our cloning strategy, because we don’t want every team member to get everything (eg: Animators don’t need environment assets). This is mainly for speed of pulling/pushing + limited disk storage.

We really wanted sparse checkout to work (along with git lfs), and we went in that direction for a while.

Unfortunately for us, (and this is the take away), git sparse checkout doesn’t play well with Git LFS because LFS expects tracked files to exist in the working tree, even if sparse checkout omits them. This often leads to LFS errors about missing objects or broken pointers during checkout.

So we came up with a simple (but probably not the best) working solution:

  1. Enable SKIP_SMUDGE to not get all the large files while cloning.
  2. This brings all the 1kb LFS pointer files, but not the blobs. (You can see the entire project’s folders, but the files won’t be in there in Unreal)
  3. Pull only the files you need (using --include or specifying in an .lfsconfig)
# Clone WITHOUT sparse checkout (but skip LFS initially)
$env:GIT_LFS_SKIP_SMUDGE=1
git clone https://<your-url>/project.git
cd avatar

# Ideally create an .lfsconfig that covers what folders or files to pull
# (with fetchinclude and fetchexclude)

# Clear the LFS skip
Remove-Item Env:GIT_LFS_SKIP_SMUDGE

# NOW - Pull ONLY LFS files you need
git lfs pull --include="Content/YourFolder/**"

Surprisingly easy!

We also provide a GUI for non-programmer folks internally to update their .lfsconfig based on what files they need.