How to set up a .gitignore file for Unity

Add a .gitignore file to your Unity project to avoid uploading unnecessary files. Learn how to customize it for your own needs.

Matthäus Niedoba
December 20, 2023
4
min read
Content

A .gitignore file is a central component for managing your Unity projects using Git, which is also the foundation of GitHub. It is a set of rules that tells Git which files to exclude from version control. It needs to be customized for each game engine. We also have a .gitignore template for Unreal Engine.

Why do you need a .gitignore?

Without it you would upload too many unnecessary files into your repository. Files in folders like Library, Temp or Logs are generated locally during your work and clutter up your repository if included. By excluding these from version control, your repository stays clean and efficient.

unity gitignore file
Using a .gitignore file will remove unnecessary files from version control

Use this example and add it to your Unity project

Download this .gitignore file and paste it to the root folder of your project. When you open it, you will see a set of rules that are specific to Unity. A .gitignore file for a Unreal Engine or a Godot project will look differently. This gitignore file works even if your Unity project is in a subfolder of your Git repository.

unity gitignore file in file browser
Paste this .gitignore file in your Unity project

Share the .gitignore file with your team

The rules in the .gitignore file should apply to everyone on your team. Therefore, the next step is to commit and push it to the repository. Afterwards, everyone should pull your commit containing the .gitignore file. In most cases, you won't need to modify it further.

Unity gitignore file in a git commit
The .gitignore file needs to be pushed to your repository with the initial commit

Customizing your .gitignore

If you have specific requirements, you can tailor your .gitignore file accordingly. For example, some people choose to ignore tools and plugins from the Unity Asset Store, while others may not. To customize, simply use a text editor to add rules. Each rule is defined by a pattern, which includes the following symbols:

Pattern Description
character.png Ignores all files that are named “character.png”
/character.png Ignores all files in the project root that are named “character.png”
*.png Ignores all PNG files
Build/ Ignores the Build folder, only if it’s in the root of your project
*/Build Ignores the Build folder only, if it’s in a subfolder
**/Build Ignores the Build folder, regardless where it is in the project. This is useful when your Git repository has a subfolder (e.g. called Unreal) where your Unreal Engine project is located.
Build/*/file.txt Ignores the file.txt if it’s inside a subfolder of the build folder. E.g. Build/something/file.txt
!*.png Include all PNG files, even if they have been ignored before
!Build/file.txt Include file.txt, even if the Build folder is ignored
/[Bb]iuld Ignores the “Build” and “build” folder. It applies to both cases. You can put multiple characters in the square brackets. For example, [BbGg]uild would ignore the folders “build”, “Build”, “guild” or “Guild”.

By adding an exclamation mark "!", you allow files and folders to be included, even if they were previously ignored.

Adding files to a .gitignore, that already have been committed

If you already committed wrong files, that should be on a .gitignore, you need to follow these steps:

  1. Add them to the .gitignore file
  2. Remove them from the Git version history using the Git command "git rm --cached <file_path>".
  3. Then, you need to commit and push your changes, even if the commit is empty and has no files

Just adding the file to the .gitignore won't be enough, because you have to remove that file from the Git history. If you are unfamiliar with the terminal, you can just launch it from your project folder.

// use this for files
git rm --cached pathToMyFile
//use this for
git rm -r --cached pathToMyFolder
remove files from Git history on a Unity project by customizing your gitignore
In Windows Explorer, type in "cmd" and press Enter. Then enter your Git command.

Adding a local (personal) .gitignore

If you need a personal .gitignore that isn't shared with the team, you can use a special file located in the hidden .git folder. Inside this folder, navigate to the info directory. Here, you'll find a file named "exclude". You can modify this file using the same rules as .gitignore, but the key difference is that these rules will only apply to your local environment and won't be shared with your team.

The exclude file can be opened with a text editor and adjusted with the same rules like the .gitignore file

Git for artists

Compatible with GitHub, simple enough for non coders and optimized for game development.
Learn about Anchorpoint

Related articles

How to login to Azure DevOps (Quick Tip)

Due to the complexity of Azure services, it's often not obvious how to log in to Microsoft's Azure DevOps portal. This quick tip will show you how.

November 15, 2024
2
min read

How to setup Multi User Editing in Unreal Engine 5.5 over the Internet

Learn more about Unreal Multi-User Editing, how to use it with version control and how to set it up over the LAN and Internet.

October 29, 2024
6
min read

Git with Blender

In this article we will explore how to use Git version control in Blender, relying on Git LFS. We will take a look at the pros and cons and which tools to use. After reading this article, you should be able to decide if this workflow is right for you.

October 16, 2024
8
min read