Gitignore for Unity: What to Ignore and What to Commit

November 11, 2026 · 11 min read

Gitignore for Unity: What to Ignore and What to Commit

A gitignore for Unity keeps the cache folders Unity rebuilds on each machine out of Git: Library/, Temp/, Obj/ and Logs/, plus personal UserSettings/ and your builds. You still commit Assets/ with every .meta file, plus Packages/ and ProjectSettings/. Below is GitHub's current template, trimmed and explained, then the subfolder trap, Git LFS and scene merging.

Why Does a Unity Project Need a .gitignore?

Open a Unity project once and the editor writes thousands of files you never touch. Library/ holds the import cache for every texture, model and script. Temp/ holds temporary data that Unity clears when you close the editor, Obj/ holds intermediate build output, and Logs/ holds import and editor logs. Unity recreates all of them as needed, so they belong to one machine, not to the project.

Commit them and two things happen. Clones get slower, because the import cache grows with every asset and holds nothing a teammate can't rebuild. Every teammate's editor also rewrites those files on each import, so you get conflicts in files nobody edited on purpose. A Unity gitignore stops both problems before the first commit.

The Gitignore for Unity, Explained Group by Group

GitHub maintains the canonical Unity.gitignore in its github/gitignore repository. Here's a trimmed version of the current file, regrouped so each block has one job:

# Folders Unity regenerates on every machine
.utmp/
/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Ll]ogs/
/[Uu]ser[Ss]ettings/
*.log

# Build output and platform packages
/[Bb]uild/
/[Bb]uilds/
/*_BackUpThisFolder_ButDontShipItWithYourGame/
/*_BurstDebugInformation_DoNotShip/
*.apk
*.aab
*.obb
*.app
*.unitypackage
*.unitypackage.meta

# Profiler captures and recordings
/[Mm]emory[Cc]aptures/
/[Rr]ecordings/

# IDE solution files and caches
.vs/
.gradle/
.consulo/
ExportedObj/
*.csproj
*.sln
*.slnx
*.suo
*.user
*.userprefs
*.pidb
*.pdb
*.mdb
*.opendb
*.VC.db
.vsconfig
*.DotSettings.user
/[Aa]ssets/Plugins/Editor/JetBrains*

# Meta files for ignored IDE and debug files
*.pidb.meta
*.pdb.meta
*.mdb.meta

# Crash, Crashlytics and recovery files
sysinfo.txt
mono_crash.*
crashlytics-build.properties
/[Aa]ssets/_Recovery/
/[Aa]ssets/_Recovery.meta

The first block is the one that matters most. UserSettings/ stores per-user editor preferences, so it's ignored like the caches. The build block covers your player builds plus the backup and Burst debug folders Unity writes next to them, which the folder names themselves warn you not to ship.

Profiler captures and recordings get large fast, and GitHub's comment notes memory captures can contain sensitive data. The IDE block drops solution and project files that your code editor integration regenerates. The crash block removes the folder Unity's crash recovery writes into Assets/ and stray crash files.

Two syntax details explain the odd look. [Ll] matches either case, so /[Ll]ibrary/ catches Library and library. The leading slash anchors each folder to the directory holding the .gitignore, which the subfolder section below explains.

The full upstream file adds lines for Addressables, the Test Framework, Visual Scripting, Blender backup files and a few other tools. Copy it from GitHub if you use those.

The template leaves out OS clutter such as .DS_Store and Thumbs.db, and its header suggests adding OS and editor rules from GitHub's Global templates. GitHub's new-repository page also offers a .gitignore chooser built from the same collection. Picking Unity there puts the file at the repo root, which only works if the Unity project is the root. A global gitignore on your own machine is another way to handle the OS clutter.

If you'd rather assemble a file, our .gitignore generator has a Unity template you can combine with OS and editor templates and your own custom patterns, then copy or download. It runs in your browser. Its Unity list isn't a line-for-line copy of GitHub's, so check it against the upstream file if you rely on a specific entry.

What to Commit in a Unity Repo: Assets, Packages and ProjectSettings

Ignoring is half the job. The other half is making sure the folders that define your project actually reach the repo.

PathCommit or ignoreWhy
Assets/CommitYour scenes, prefabs, scripts and art, each with its .meta file
Packages/manifest.jsonCommitLists the packages and versions the project depends on
Packages/packages-lock.jsonCommitRecords the resolved package versions
ProjectSettings/CommitTags, layers, input, quality, physics and editor settings everyone shares
.gitignore, .gitattributesCommitEveryone needs the same ignore and LFS rules
Library/, Temp/, Obj/, Logs/IgnoreCaches and logs Unity rebuilds locally
UserSettings/IgnorePersonal editor preferences
*.csproj, *.slnIgnoreRegenerated by your code editor integration
Build/, Builds/IgnorePlayer builds belong in releases or artifact storage

Unity's lock file docs say to put packages-lock.json under source control so every machine resolves the same package set. If Packages/ also contains embedded package folders, commit those too, because they're source you wrote or modified.

A repo usually needs a few files Unity doesn't create. Add a README so people know which Unity version to install. Our README guide covers what to put in it, and the GitHub Markdown cheat sheet shows how GitHub renders it. Design notes and build steps can live in a Docs/ folder as plain Markdown, as described in our guide to writing documentation in Markdown.

Why You Commit .meta Files and Never Ignore Them

Every asset and folder under Assets/ gets a .meta file next to it. According to Unity's asset metadata docs, it holds the asset's unique ID and its import settings. Scenes and prefabs point to other assets by that ID, not by file name.

Lose the .meta file and Unity treats the asset as brand new with a fresh ID. Every reference to it breaks. Materials lose their textures, and GameObjects show an empty script slot. That's why a teammate who clones a repo without .meta files sees a project full of missing references.

Check the setting at Edit > Project Settings > Version Control. The Mode should be Visible Meta Files, which Unity's docs list as the default. It's the mode for version control systems Unity doesn't support directly, and Git is one of them. Your OS may still hide .meta files in the file browser, but Git sees them.

Older copies of the template contained !/[Aa]ssets/**/*.meta to re-include meta files. The current file doesn't need it, because nothing in it ignores .meta files in general. The .meta lines it does ignore, such as *.pdb.meta, *.unitypackage.meta and /[Aa]ssets/_Recovery.meta, belong to files or folders that are ignored anyway.

Where Does the .gitignore Go When Unity Isn't the Repo Root?

GitHub's template starts with the comment that it belongs at the root of your Unity project directory. That matters because of the leading slash. The gitignore docs say a pattern with a slash at the beginning or middle is relative to the directory of the .gitignore file itself.

This layout breaks it:

my-game-repo/
├── .gitignore        (contains /[Ll]ibrary/)
├── README.md
└── Game/
    ├── Assets/
    ├── Library/      (not matched, gets committed)
    ├── Packages/
    └── ProjectSettings/

/[Ll]ibrary/ only matches my-game-repo/Library/, which doesn't exist. Game/Library/ sails straight into your first commit. You have two clean fixes:

  1. Move the Unity .gitignore into Game/. Git reads a .gitignore in any folder, and its anchored patterns then resolve against Game/.
  2. Keep one root file and prefix each path, for example /Game/[Ll]ibrary/ and /Game/[Tt]emp/.

We prefer the first option, even in a monorepo with a server or tools folder beside the game. You can paste GitHub's file into Game/ unedited and update it later by replacing it. A server folder beside it can carry its own file, such as a Node gitignore or a Visual Studio gitignore for C#.

Don't fix it by deleting the slashes. A pattern like [Bb]uild/ without a leading slash matches at any depth. It would also ignore a folder called Build inside a plugin under Assets/, and that plugin's files would quietly never reach the repo.

Removing Library/ After You Already Committed It

A .gitignore doesn't touch files Git already tracks. If Library/ slipped into an earlier commit, add the .gitignore first, then remove the cache folders from the index while keeping them on disk:

git rm -r --cached --ignore-unmatch Library Temp Obj Logs UserSettings
git commit -m "Stop tracking Unity cache folders"
git check-ignore -v Library/

--cached removes the paths from Git's index only, so your local Library/ stays and Unity doesn't reimport everything. --ignore-unmatch stops the command from failing when one of those folders was never tracked. The last line proves the rule works: it prints the .gitignore file, line number and pattern that matched. No output means no rule matched, which usually points back to the subfolder problem above.

This stops future commits from carrying the cache. The old commits still contain it, so the repo stays large until you rewrite history, which is a separate job.

Git LFS for Textures, Audio and Models

A gitignore for Unity keeps caches out, but your real assets still bloat history. Every edit to a 50 MB texture or audio file adds another version to history, and every clone downloads all of them. Git LFS replaces those files in the repo with small pointers and stores the content separately.

git lfs install
git lfs track "*.psd" "*.fbx" "*.wav" "*.png"
git add .gitattributes
git commit -m "Track large binaries with Git LFS"

git lfs install runs once per user account. git lfs track writes the patterns to .gitattributes, which you commit so the whole team uses the same rules. Pick the binary types your project actually uses.

Keep .unity, .prefab and .meta files out of LFS. With Force Text serialization they're YAML text, so Git can diff them and UnityYAMLMerge can merge them. Tracking only applies to files you add from now on. Binaries already in history stay there until you migrate them. Storage and bandwidth quotas depend on your Git host, so check its LFS limits before you push a large art folder.

Merging Scenes and Prefabs with UnityYAMLMerge

When two people edit the same scene, Git's line merge often produces a broken file. Unity ships a merge tool called UnityYAMLMerge that understands the scene format. It needs text serialization, set at Edit > Project Settings > Editor > Asset Serialization > Mode. Unity's docs list Force Text as the default.

Unity's Smart Merge page gives this config for .git/config, or for ~/.gitconfig to cover every repo:

[merge]
tool = unityyamlmerge

[mergetool "unityyamlmerge"]
trustExitCode = false
cmd = '<path to UnityYAMLMerge>' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"

Replace the path with your editor's copy. In a default Unity Hub install on Windows, it's C:\Program Files\Unity\Hub\Editor\<version>\Editor\Data\Tools\UnityYAMLMerge.exe. On macOS it's /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/Helpers/UnityYAMLMerge. After a conflict, run git mergetool to hand the files to it.

The tool merges .unity, .prefab and .meta files. Other YAML assets such as .mat, .asset and .controller go to a fallback merge tool unless you pass --force. It also can't resolve every conflict, so two people rearranging the same objects can still clash. Splitting work into separate scenes and prefabs avoids more conflicts than any merge tool fixes.

A good gitignore for Unity is easy to read once you know why each block exists. Caches and builds stay out, .meta files go in, and the file sits in the Unity project folder. Add Git LFS and UnityYAMLMerge on top to handle the two problems a .gitignore can't. Build your starting file with the .gitignore generator, then write the project README in our free Markdown editor and download the .md.