# 7. Pitfalls and When to Stay on Git Part of [[UVCS]]. Previous: [[6. Worked Example Day-One UVCS]]. Hub: [[UVCS]]. Cross-links: [[5. Clients and UVCS Comparison]] · [[6. Pitfalls]] (Git series) · [[Version Control]] ## 7.1 UVCS-specific pitfalls | Pitfall | Symptom | Fix | |---|---|---| | Checked in `Library/` | Multi-GB Changeset, broken machines | Delete from repo history carefully (admin ops); strengthen `ignore.conf`; never re-add | | Ignored `ProjectSettings` or `Assets` | Teammates cannot open project | Remove those rules; check in the real project spine ([ignore docs](https://docs.unity.com/en-us/unity-version-control/ignore-files)) | | Forgotten Smart Lock | Artist blocked Friday night | Admin/owner releases lock; teach Retained vs Locked ([[4. Branches Smart Locks Exclusive Checkout]]) | | Lock on stale revision | Checkout fails | Update / switch to latest on destination branch | | Replica + Smart Locks | Outdated lock state | Smart locks don't travel across replicas — avoid replica topologies for class | | Two VCS on one folder | Git + UVCS metadata fighting | One primary VCS; migrate deliberately | | Merge-to + locks | Unexpected unlock/merge behavior | Docs: merge-to does not support locks | | Encrypted repo via Hub only | Cannot add project | Desktop client + key first ([Hub docs](https://docs.unity.com/en-us/unity-version-control/get-started-vcs-hub)) | | Scene still thrashes | Lock churn on `Level_01.unity` | Prefab isolation ([[4. Conflicts Prefabs and Branching]]), additive scenes ([[SceneManagement in Unity 6]]) | ## 7.2 Shared pitfalls (Git or UVCS) These are process problems, not product bugs — see also [[6. Pitfalls]]: - Missing `.meta` for a new asset (GUID break). - Moving assets in Explorer instead of Unity (meta orphan). - Mixing Force Text / Force Binary across machines. - Giant binary commits without locks (Git LFS or Smart Locks). ## 7.3 When to stay on Git + GitHub Reuse the decision table in [[5. Clients and UVCS Comparison]]. Short rubric for Marshall's teaching context: **Stay on Git + GitHub when:** - Solo / small engineering-heavy class projects. - Students already assessed on GitHub PRs / Desktop flows ([[Setting Up GitHub for Unity]], [[Connecting an Existing Unity Project to a New GitHub Repository Using GitHub Desktop]]). - Binary footprint fits GitHub + disciplined LFS ([[2. Git LFS]]). - You need maximum portability and CI familiarity (CI is a future Pipelines topic — not linked yet). **Choose UVCS when:** - Binary / cinematic churn makes LFS quotas or lock UX the bottleneck. - Mixed artist + engineer cohort benefits from **Gluon** + **Smart Locks**. - Org already standardized on Unity Dashboard / DevOps. ## 7.4 Migration honesty UVCS documents migrating from Git. Treat migration as a **scheduled project** with a freeze window — not a Thursday night experiment on the shipping class midterm repo. Prefer greenfield UVCS labs ([[6. Worked Example Day-One UVCS]]) for first exposure. ## 7.5 See also (series) - [[Version Control]] — Git Pipelines hub - [[5. Clients and UVCS Comparison]] — side-by-side product comparison - [[UVCS]] — this hands-on hub