Unity Project Hygiene

Unity Project Hygiene Skill

Maintain a clean, CI-friendly Unity repository.

See also: Shared Conventions | Safety Guidelines

Purpose

Keep the repository stable, fast to clone, and ready for automated builds.

Git LFS

When to Use LFS

Large binary files that change infrequently:

• Textures (.png, .jpg, .psd, .tga)
• Audio (.wav, .mp3, .ogg)
• 3D models (.fbx, .obj, .blend)
• Video (.mp4, .mov)

Setup LFS

# Install LFS
git lfs install

# Track file types
git lfs track "*.png"
git lfs track "*.jpg"
git lfs track "*.psd"
git lfs track "*.wav"
git lfs track "*.mp3"
git lfs track "*.fbx"
git lfs track "*.blend"

# Commit .gitattributes
git add .gitattributes
git commit -m "Configure Git LFS for binary assets"

Verify LFS

# List tracked patterns
git lfs track

# List LFS files
git lfs ls-files

# Check file is LFS-tracked
git lfs pointer --check Assets/Textures/large.png

.gitignore

Required Unity Ignores

# Unity generated
/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Bb]uild/
/[Bb]uilds/
/[Ll]ogs/
/[Uu]ser[Ss]ettings/

# Memory captures
/[Mm]emoryCaptures/

# Asset meta data should be committed (don't ignore .meta)

# Autogenerated VS/Rider files
.vs/
.idea/
*.csproj
*.unityproj
*.sln
*.suo
*.tmp
*.user
*.userprefs
*.pidb
*.booproj

# Build results
*.apk
*.aab
*.unitypackage
*.app

# Crashlytics
crashlytics-build.properties

# OS files
.DS_Store
Thumbs.db

Verify .gitignore Working

# Check if ignored
git check-ignore -v Library/
git check-ignore -v Temp/

# List untracked files (should not show Library, Temp, etc.)
git status --porcelain

ProjectSettings Sanity

Key Files to Track

ProjectSettings/
  ProjectSettings.asset      # Most settings
  EditorBuildSettings.asset  # Build scenes
  TagManager.asset           # Tags and layers
  InputManager.asset         # Input settings
  QualitySettings.asset      # Quality levels
  GraphicsSettings.asset     # Rendering

Verify No Local-Only Settings

# Check for user-specific paths or settings
grep -r "Users/\|C:\\\|/home/" ProjectSettings/

Required Settings for CI

In ProjectSettings/ProjectSettings.asset:

# Enable visible meta files
  externalVersionControlSupport: Visible Meta Files

# Force text serialization
  serializationMode: 2  # 2 = Force Text

# Set scripting backend for target platform
  scriptingBackend:
    Standalone: 1  # 1 = IL2CPP, 0 = Mono

Packages/manifest.json

Verify Package Versions

cat Packages/manifest.json | python3 -c "import json,sys; d=json.load(sys.stdin); print('\n'.join(f'{k}: {v}' for k,v in sorted(d.get('dependencies',{}).items())))"

Lock File

Packages/packages-lock.json should be committed for reproducible builds.

Common Issues

# Check for git URLs (may need auth in CI)
grep "git+" Packages/manifest.json

# Check for local paths (won't work in CI)
grep "file:" Packages/manifest.json

CI Gates

Build Script Check

Verify build script exists and is callable:

grep -r "static void.*Build\|static void.*CI" Assets/Editor/

Test Script Check

grep -r "UnityTest\|\[Test\]" Assets/Tests/

Pre-commit Checklist

# 1. No uncommitted changes to critical files
git diff --name-only | grep -E "manifest.json|ProjectSettings"

# 2. Library not committed
git ls-files | grep -i "^Library/" && echo "ERROR: Library committed!"

# 3. Meta files present for all assets
find Assets -type f ! -name "*.meta" -exec sh -c 'test -f "$1.meta" || echo "Missing: $1.meta"' _ {} \;

Workflow: New Project Setup

# 1. Initialize repo
git init
git lfs install

# 2. Add .gitignore
# (copy from above)

# 3. Configure LFS
git lfs track "*.png" "*.jpg" "*.psd" "*.wav" "*.mp3" "*.fbx"
git add .gitattributes

# 4. Verify settings
grep "serializationMode: 2" ProjectSettings/ProjectSettings.asset || echo "WARNING: Not force text!"

# 5. Initial commit
git add -A
git commit -m "Initial Unity project setup"

Workflow: Pre-PR Check

# 1. Verify clean state
git status

# 2. Check no binaries without LFS
git diff --cached --name-only | xargs -I{} sh -c 'file -b "{}" | grep -q "data\|image" && echo "Binary: {}"'

# 3. Verify project compiles
unity -quit -batchmode -nographics -projectPath . -logFile /tmp/check.log
echo "Exit: $?"

Policies

• Always commit .meta files - Unity needs them for asset references
• Never commit Library/ - it's regenerated
• Use LFS for binaries - keeps repo fast
• Force text serialization - enables meaningful diffs
• Lock package versions - reproducible builds