Size does matter…sometimes…
GitHub size limitation
While recently working on a project I found that GitHub, and GitHub specifically, has a file size limit of 100Mb for a single file. This is a limit that you would rarely reach with C# code files but we’re building video games here! So, what are our options? Well, we could choose a different git provider but that is mighty inconvenient now isn’t it? Enter Git LFS. WHat’s Git LFS? Let’s take a look.
Git LFS, which stands for Large File Storage, is an extension to git that allows for large files to be stored in a separate location from the usual files in a repository and replaced in the repo with a pointer to the file. This not only allows us to get around the 100Mb file limit that GitHub imposes but it also allows us to reduce the time it takes to update or restore our repositories because the pointer, which is written into the git history every time a commit is made, is drastically smaller than the file it points to.
So now that we know what Git LFS is how do we know which files to store with pointers? This is accomplished in much the same way as we ignore files we don’t want by using a .gitignore file in our repository. When we use GitKraken or GitHub itself to initialize our repository to use Git LFS, a .gitattributes file is automatically created and we can list what file types we want to be tracked and stored using Git LFS. If we are using a different method for initializing our repository we can still manually add a .gitattributes file.
So how do we do it?
Alright, you might have noticed that I said we needed to initialize our repo to use Git LFS. First, we need to install it on our systems. We can download it from the Git LFS website https://git-lfs.github.com once installed we can initialize our repo for Gt LFS in several ways. If we are utilizing the git command line tools we can type
NOTE: We only need to do this once for our account.
Once we have it installed and the repo is set up to use Git LFS we can start adding file extensions to our .gitignore file. We can add these extensions one by one using the following command
While this works it’s simply cumbersome for the number of file extensions we need to accommodate in a standard Unity project. For that reason alone, I use a prebuilt .gitattributes that I found at https://thoughtbot.com/blog/how-to-git-with-unity. This file looks like
The last thing we need to remember to do is to add it to our repo and check it in.
It should be noted that initializing an existing repository and adding a .gitattribute file does not automatically convert existing files that should be tracked into LFS tracked files. There is a tool provided at the repo for git lfs migrate to help with this conversion.
As game developers, it is going to be a frequent occurrence that we have files and assets that we want to be kept with our repository and shared between developers. Git LFS can help us do this while improving the performance of retrieving our repositories. It also has the happy side-effect of allowing us to get around the 100Mb file size limit from GitHub. If you enjoyed this article, or want to come along with me as I progress on my journey, follow me at gamedevchris.medium.com.