Set Up Git LFS to Manage Large Files in Unity

Unity projects often include large assets, such as high-resolution textures, 3D models, and audio files. These large files can quickly exceed GitHub’s file size limits or slow down collaboration. Git Large File Storage (LFS) is a Git extension that helps solve this problem. Instead of storing these large files directly in your main repository, Git LFS stores them externally while keeping track of them in Git. This keeps your project lightweight and fast.

When you create a new local repository with GitHub Desktop, it installs Git LFS for you, but it doesn’t always generate a .gitattributes file. This file is required to configure which file types should be tracked with Git LFS.

GitHub has a file size limit of 100 MB for individual files. If you attempt to commit a file larger than this directly to Git, it will reject it. This step demonstrates what happens when a file exceeds that limit and highlights why you'll need Git LFS to manage such assets effectively.

Instructions

1. Download and save a large sample file

• Download the large sample file provided and save it in your Unity project under Assets > Art.

2. Attempt to commit the changes in GitHub Desktop

• Open GitHub Desktop.
• Try to commit the changes to the project as you would normally.
• A warning will appear, stating that the files are over 100 MB and will cause problems when committed.
• Select Cancel when prompted.

You have now experienced the GitHub file size limit, demonstrating why standard Git is insufficient for large Unity assets.

Git LFS allows GitHub to handle large files without exceeding size limits. While GitHub Desktop installs Git LFS automatically, you still need a .gitattributes file to tell Git which specific file types to manage with Git LFS. This file configures Git to track references to large files instead of their full content.

Instructions

1. Download and save the .gitattributes file

• Download the provided zip file that contains a sample .gitattributes file.
• Unzip the downloaded file, then open the folder to find the .gitattributes file (On Windows, right-click on the file and select Extract All. On macOS, double-click on the file).
• If you are on macOS and do not see the .gitattributes file inside the folder, press Cmd + Shift + . (period) to toggle the visibility of hidden files.
• Place the .gitattributes file in the root folder of your Unity project. This is the same folder that contains your .gitignore and .git folders.

Important: If you already have a .gitattributes file, feel free to overwrite it with this new one.

2. Review the .gitattributes file

• If you want to explore the contents of this file or edit it, open it in a text editor (for example, VS Code, Notepad++, Sublime Text). You'll see entries like *.psd filter=lfs diff=lfs merge=lfs -text. This configures Git LFS to track all Photoshop Document files (.psd) by storing a small pointer file. This pointer file contains a reference to the actual large file, which is then stored separately on a Git LFS server. This approach keeps your main Git repository lightweight and fast.

3. Commit the .gitattributes file

• Open GitHub Desktop.
• In the Summary box, enter “Added .gitattributes file for LFS”.
• Select Commit to main.

4. Push your changes to GitHub

• Select Push origin to upload the changes.
• Notice that the warning has disappeared, and Git LFS is now activated and configured for your Unity project.

Tip: You can find more examples of Unity-ready .gitattributes files online for Unity and many other project types that are maintained by other people, such as gitattributes for Unity projects.

You can read more about Configuring Git Large File Storage and Collaboration with Git Large File Storage in the official GitHub documentation.

In this tutorial, you learned why Git LFS is necessary for Unity projects, saw how large files trigger GitHub’s limits, and configured your repository to use Git LFS with a .gitattributes file.

In the next tutorial, you’ll learn how to create and manage branches, which are essential for isolating feature development and streamlining teamwork in a collaborative environment.