# 1. Serialization, Meta Files, and `.gitignore` **Target:** Unity 6000.5+. Part of [[Version Control]]. Lighter first-time setup: [[Setting Up GitHub for Unity]]. ## Why this comes first Git only helps if Unity writes assets as **text** and keeps **`.meta` GUID identity** on disk where Git can see it. Binary scenes produce opaque diffs; hidden metas make clones lose references. Everything later (LFS, Smart Merge, Prefab isolation) assumes these two settings. Official overview: [Version control (Unity 6000.5)](https://docs.unity3d.com/6000.5/Documentation/Manual/VersionControl.html). ## Step 1 — Force Text serialization 1. Open the project in the Editor. 2. **Edit > Project Settings > Editor**. 3. Under **Asset Serialization**, set **Mode** to **Force Text**. 4. **File > Save Project**. **What this does:** Scenes (`.unity`), Prefabs (`.prefab`), ScriptableObjects, Materials, and other YAML-capable assets serialize as text. Git can diff and (with [[3. UnityYAMLMerge Smart Merge]]) merge them semantically. **What NOT to expect:** Text serialization does **not** turn textures, audio, meshes, or FBX into text. Those remain binaries — handle them with [[2. Git LFS]]. **Check:** Open any `.unity` or `.prefab` in a text editor. You should see YAML starting with `%YAML 1.1` / `%TAG !u!` and `--- !u!` document markers — not a binary blob. > [!tip] > New Unity 6 projects usually default to Force Text. Still verify on inherited or upgraded projects; an old **Force Binary** or **Mixed** setting silently breaks mergeability. ## Step 2 — Visible Meta Files 1. **Edit > Project Settings > Version Control**. 2. Set **Mode** to **Visible Meta Files** (default for non-Perforce / non-UVCS Mode). 3. Save the project. Unity docs: for a VCS Unity does not drive inside the Editor (plain Git), use **Visible Meta Files** so the OS and Git see every `.meta` next to its asset. See [Version control integrations](https://docs.unity.com/en-us/engine/6000.0/manual/get-started/project-configuration/version-control/versioncontrolintegration). **Never ignore `.meta` files.** Each `.meta` stores the asset GUID. Inspector references, Prefab links, and Addressable/group mappings resolve by GUID — not by path alone. Commit asset + `.meta` together; rename/move **inside** the Editor so Unity updates both. Unity blog guidance (meta always checked in): [How to Author Scenes and Prefabs with Version Control](https://unity.com/blog/author-scenes-and-prefabs-with-verson-control). ## Step 3 — What Git must track | Path | Track? | Why | |---|---|---| | `Assets/` (including every `.meta`) | **Yes** | Game content + GUID identity | | `Packages/manifest.json`, `Packages/packages-lock.json` | **Yes** | Package set / resolved versions | | `ProjectSettings/` | **Yes** | Player, quality, XR, input, Editor settings | | `.gitignore`, `.gitattributes` | **Yes** | Repo policy for every clone | | `Library/` | **No** | Regenerable import cache (often multi-GB) | | `Temp/`, `Obj/`, `Logs/` | **No** | Ephemeral | | `UserSettings/` | **No** | Per-user layout / prefs | | `Build/`, `Builds/`, player artifacts | **No** | Rebuildable outputs | ## Step 4 — Recommended Unity `.gitignore` Place `.gitignore` at the **project root** (sibling of `Assets/`, `Packages/`, `ProjectSettings/`). Prefer the maintained community/GitHub template rather than inventing one: - Template (raw): https://raw.githubusercontent.com/github/gitignore/main/Unity.gitignore - Browse: https://github.com/github/gitignore/blob/main/Unity.gitignore Core of that template (verify against the live file when you copy — templates evolve): ```gitignore # This .gitignore file should be placed at the root of your Unity project directory # # Get latest from https://github.com/github/gitignore/blob/main/Unity.gitignore # .utmp/ /[Ll]ibrary/ /[Tt]emp/ /[Oo]bj/ /[Bb]uild/ /[Bb]uilds/ /[Ll]ogs/ /[Uu]ser[Ss]ettings/ *.log /[Mm]emory[Cc]aptures/ /[Rr]ecordings/ /[Aa]ssets/Plugins/Editor/JetBrains* *.DotSettings.user .vs/ .gradle/ ExportedObj/ .consulo/ *.csproj *.unityproj *.sln *.slnx *.suo *.tmp *.user *.userprefs *.pidb *.booproj *.svd *.pdb *.mdb *.opendb *.VC.db *.pidb.meta *.pdb.meta *.mdb.meta sysinfo.txt .dirstamp mono_crash.* tmpinst-dir.stamp /*_BackUpThisFolder_ButDontShipItWithYourGame/ /*_BurstDebugInformation_DoNotShip/ *.apk *.aab *.obb *.unitypackage *.unitypackage.meta *.app crashlytics-build.properties /[Aa]ssets/**/*.blend1 /[Aa]ssets/**/*.blend1.meta /[Aa]ssets/**/TDImportCache/ /[Aa]ssets/**/TDImportCache.meta /[Aa]ssets/_Recovery/ /[Aa]ssets/_Recovery.meta /[Aa]ssets/AddressableAssetsData/*/addressables_content_state.bin /[Aa]ssets/AddressableAssetsData/*/addressables_content_state.bin.meta /[Aa]ssets/AddressableAssetsData/link.xml /[Aa]ssets/AddressableAssetsData/link.xml.meta /[Aa]ssets/Addressables_Temp/ /[Aa]ssets/Addressables_Temp.meta /[Aa]ssets/StreamingAssets/aa/ /[Aa]ssets/StreamingAssets/aa.meta /ServerData/ /[Aa]ssets/GeneratedLocalRepo/ /[Aa]ssets/GeneratedLocalRepo.meta /[Aa]ssets/Plugins/Android/**/*.gradle.backup* /[Aa]ssets/Plugins/Android/**/local.properties /[Aa]ssets/Resources/PerformanceTestRunInfo.json /[Aa]ssets/Resources/PerformanceTestRunInfo.json.meta /[Aa]ssets/Resources/PerformanceTestRunSettings.json /[Aa]ssets/Resources/PerformanceTestRunSettings.json.meta /[Aa]ssets/InitTestScene*.unity /[Aa]ssets/InitTestScene*.unity.meta /[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Core/Property Providers/ /[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Core/Property Providers.meta /[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Flow/UnitOptions.db /[Aa]ssets/Unity.VisualScripting.Generated/VisualScripting.Flow/UnitOptions.db.meta /UIElementsSchema/ /[Aa]ssets/[Ss]ceneDependencyCache* ``` When creating a repo on github.com, choosing the **Unity** `.gitignore` template seeds the same family of rules. See also the Desktop quickstart: [[Connecting an Existing Unity Project to a New GitHub Repository Using GitHub Desktop]]. ## What NOT to ignore Do **not** add blanket rules like: ```gitignore # BAD — never do these *.meta Assets/ ProjectSettings/ Packages/ *.unity *.prefab *.asset ``` Also avoid ignoring entire content folders you actually need (`StreamingAssets` game data, localization tables, ScriptableObject databases). Ignore **regenerable caches and personal IDE noise**, not game identity. ## Step 5 — First commit hygiene ```bash cd /path/to/YourUnityProject git status ``` Confirm `Library/`, `Temp/`, `Logs/`, `UserSettings/` are **not** listed as untracked. If they are, your `.gitignore` is missing or in the wrong directory. ```bash git add .gitignore git add Assets Packages ProjectSettings git status # review the staged set carefully git commit -m "Initial Unity project (Force Text, Visible Meta Files)" ``` Never use a blind `git add -A` on day one without reading `git status` — that is how `Library/` enters history (see [[6. Pitfalls]]). ## Tie-in to architecture Keeping code in asmdefs and gameplay data in ScriptableObjects ([[Architecture and Code Patterns]]) shrinks how often a single `.unity` file churns. Serialization settings make that structure *diffable*; structure makes merges *rare*. ## Next [[2. Git LFS]] — which binaries to track, `.gitattributes`, and locking caveats.