# 6. Pitfalls **Target:** Unity 6000.5+. Part of [[Version Control]]. Read after [[1. Serialization Meta and Gitignore]] and [[2. Git LFS]]. ## 1. `Library/` (or `Temp/`, `Logs/`) committed **Symptom:** Multi-gigabyte clone; constant noisy diffs; “works on my machine” import database fights. **Cause:** Missing/wrong `.gitignore`, or `git add -A` before ignore rules existed. **Fix going forward:** Restore proper Unity `.gitignore` ([[1. Serialization Meta and Gitignore]]). **Fix history (destructive — coordinate):** remove from Git history with a history-rewriting tool (`git filter-repo` is what GitHub recommends for removing large files from history — see [About large files on GitHub](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github)). Everyone must re-clone or carefully reset. **Not demonstrated live here.** ```bash # Stop the bleeding on the next commit (keeps files on disk) git rm -r --cached Library Temp Logs UserSettings git commit -m "Stop tracking Unity regenerable folders" ``` Unity regenerates `Library/` on open — that is expected. ## 2. Meta mismatches / Missing references **Symptoms:** Missing Script, missing Prefab link, pink materials, silent null refs after pull. **Causes:** - Committed an asset without its `.meta` (GUID regenerated on another machine). - Deleted `.meta` but kept the asset (or the reverse). - Renamed/moved files in Explorer/Finder instead of the Unity Project window. - Merged one side’s asset and the other side’s meta incorrectly. **Prevention:** - Visible Meta Files on ([[1. Serialization Meta and Gitignore]]). - Always stage **pairs**: `Foo.cs` + `Foo.cs.meta`. - Move/rename **inside** Unity. - Code review checklist: “any new asset without meta?” **Recovery sketch:** 1. Find the GUID the scene/Prefab still references (YAML `guid:` fields). 2. Search the repo history for a `.meta` that owned that GUID. 3. Restore that meta, or retarget references in the Editor and accept a new GUID only if you control all dependents. ## 3. Force Binary / Mixed serialization still on **Symptom:** “Git says the whole scene changed” every save; UnityYAMLMerge useless. **Fix:** Project Settings → Editor → Asset Serialization → **Force Text**, then re-save assets. Expect a one-time large text conversion commit. ## 4. LFS bandwidth and storage surprises **Symptoms:** `git push` / clone fails; GitHub emails about quota; teammates get pointer files only. **Causes:** - Tracking huge folders unnecessarily (every PNG in the project). - Re-exporting binaries constantly (new OID every time → full upload). - Collaborators without `git lfs install`. - Migrated late — large blobs still in Git history **and** LFS. **Mitigations:** - Track selectively ([[2. Git LFS]]). - Prefer stable source art; avoid commit-spam of DCC autosaves (`.blend1` is already in the Unity gitignore template). - Watch GitHub LFS data/bandwidth for the org/plan ([About Git LFS](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-git-large-file-storage)). - Document “install Git LFS” in the course README. > Quotas and UI labels change — verify on GitHub’s current billing/LFS docs rather than memorizing numbers from this note beyond the published per-file maxima. ## 5. Large binary thrash without LFS Pushing a **> 100 MiB** file without LFS is **blocked** by GitHub ([About large files](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github)). Even 50–100 MiB files warn and hurt repo health. If already pushed: remove from history (filter-repo / BFG-style workflows per GitHub docs), then `git lfs track` **before** re-adding. ## 6. Line ending and YAML churn Windows vs macOS can rewrites line endings and cause whole-file diffs. For Unity YAML, many teams set: ```gitattributes * text=auto *.cs text diff=csharp *.shader text *.unity text eol=lf *.prefab text eol=lf *.asset text eol=lf *.meta text eol=lf ``` Combine carefully with LFS rules (LFS patterns use `-text`). Test on a throwaway branch — **not verified live here.** ## 7. Generated IDE and package noise - `*.csproj` / `*.sln` should stay ignored (Unity regenerates). - Rider/`*.DotSettings.user` personal layers — ignored in the Unity template. - Addressables `addressables_content_state.bin` and `StreamingAssets/aa/` — template ignores defaults; full Addressables pipeline is a **future Pipelines** topic. - `_Recovery/` under Assets — crash recovery; ignore (in current Unity.gitignore). ## 8. Merging while Unity has the project open The Editor may refresh and rewrite YAML mid-merge, re-dirtying files or locking binaries. **Habit:** close the project (or at least stop Play Mode and focus elsewhere) during hard merges; reopen after `git add` of resolved assets. ## 9. “Commit all” scene dirt Moving a camera or clicking a Prefab instance can dirty lighting data, occlusion, or Sprite Atlases. Review diffs before commit ([Unity VCS best practices](https://unity.com/how-to/version-control-systems)). ```bash git diff --stat git diff Assets/Scenes/Level_01.unity | less ``` If you did not mean to change lightmaps, discard those files from the commit. ## 10. Assuming Desktop configured Smart Merge GitHub Desktop will not replace a proper `mergetool.unityyamlmerge` setup. When Desktop reports a conflicted `.unity`, finish with CLI mergetool ([[3. UnityYAMLMerge Smart Merge]], [[5. Clients and UVCS Comparison]]). ## Quick triage checklist | Symptom | First check | |---|---| | Clone is huge | Is `Library/` in history? `git rev-list --objects --all | sort -k2` / git-sizer | | Missing refs after pull | Missing `.meta`? GUID change? | | Cannot push 120 MB FBX | LFS track + migrate | | Teammate sees 1 KB “textures” | Pointer file — install LFS, `git lfs pull` | | Scene conflict soup | UnityYAMLMerge; then Prefab-isolate for next time | | Endless binary diffs | Should this extension be LFS? Is art being re-exported needlessly? | ## See also - Hub: [[Version Control]] - Quickstarts: [[Setting Up GitHub for Unity]], [[Connecting an Existing Unity Project to a New GitHub Repository Using GitHub Desktop]]