.uversionignore

Introduzione

Il file .uversionignore alla radice del workspace definisce i file e le cartelle che il client non deve mai tracciare, caricare o includere nei commit. Sintassi in stile .gitignore (un sottoinsieme: commenti, pattern di cartella terminati con / e glob di nome/estensione), compilata da globset. Non è un gitignore completo: la negazione con ! e l'ancoraggio non sono supportati. Alcune regole specifiche di Unreal Engine sono documentate più sotto.

Il file viene creato automaticamente dal client desktop al momento del clone con un template UE5 predefinito. Puoi poi modificarlo per adattarlo al tuo progetto.

Il file è tracciato a sua volta: se lo modifichi e lo commiti, i tuoi collaboratori ricevono le tue modifiche al prossimo sync. È intenzionale: tutto lo studio ha le stesse regole di esclusione.

Sintassi

Una regola per riga. Le righe vuote e quelle che iniziano con # vengono ignorate (commenti).

Pattern di base

Wildcard

Nessuna negazione (!)

A differenza di .gitignore, uVersion non supporta il prefisso ! per reincludere un file. Una riga che inizia con ! è trattata come un pattern letterale, non come un'eccezione. Il ri-tracking dei file all'interno di una cartella ignorata avviene solo tramite le regole automatiche: l'eccezione ThirdParty e la whitelist dei Binaries/ dei plugin installati (vedi sotto).

Commenti

# Build artifacts (regénérés à chaque build, jamais à versioner)
Binaries/
Intermediate/

Un # a metà riga non è un commento: fa parte del pattern. Solo un # a inizio riga (dopo eventuale spazio bianco) avvia un commento.

Precedenza delle regole

L'ordine delle righe nel file non ha alcuna importanza: tutti i pattern sono compilati in un unico GlobSet e un percorso viene ignorato non appena corrisponde a uno di essi. La decisione segue una precedenza fissa, in quest'ordine:

1. Percorso riservato Plugins/uVersion: sempre ignorato (cartella gestita dallo strumento, distribuzione binaria), anche se una regola tentasse di includerlo.
2. Componente ThirdParty: se un segmento del percorso si chiama esattamente ThirdParty, il file non viene mai ignorato.
3. Prefisso di plugin in whitelist (Binaries/ di un plugin installato): mai ignorato.
4. Altrimenti: il percorso viene ignorato se corrisponde a un pattern del file.

Template UE5 predefinito

Ecco esattamente ciò che il client desktop genera al momento del clone in un workspace UE5:

# uVersion ignore - Unreal Engine 5 defaults
# Note: Installed plugins, ThirdParty directories, and plugins with
# external library dependencies are automatically whitelisted.

# Build & intermediate (regenerated by UE5)
Binaries/
Build/
DerivedDataCache/
Intermediate/
Packages/
Saved/

# IDE / editor
.vs/
.vscode/
.idea/
.vsconfig
*.sln
*.suo
*.sdf
*.opensdf
*.opendb
*.ncb
*.user

# Build artifacts
*.pdb
*.obj
*.o
*.lib
*.dll
*.so
*.dylib
*.exe
*.exp
*.ilk
*.iobj
*.ipdb
*.pch
*.ipch
*.res
*.tlog
*.manifest

# Logs & temp
*.log
*.tmp
*.bak
*.swp

# OS files
Thumbs.db
.DS_Store
desktop.ini

Puoi aggiungere le tue regole a questo file. Ricordati di committarlo affinché tutto lo studio abbia le stesse esclusioni.

Plugin

Cartella riservata Plugins/uVersion

La cartella Plugins/uVersion (il plugin uVersion stesso) è sempre ignorata, a qualsiasi profondità, e questa regola prevale su tutto il resto. È gestita dal client desktop (distribuzione binaria) e non deve mai essere committata. Le cartelle vicine come Plugins/uVersionExtras non sono interessate.

uVersion applica anche una logica intelligente per gli altri plugin, senza nulla da scrivere nel file:

• Se un plugin ha "Installed": true nel suo .uplugin e non ha una cartella Source/ (plugin puramente binario, tipo Marketplace) → i suoi Binaries/ sono in whitelist e quindi tracciati. È corretto: per un plugin binario, le .dll compilate sono il plugin.
• Se il plugin ha una cartella Source/ (ricompilabile) o non ha "Installed": true → i suoi Binaries/ e Intermediate/ sono ignorati come per il progetto principale (i binari sono artefatti rigenerati al build).

Questa logica evita di dover mantenere manualmente le eccezioni per i plugin commerciali scaricati dall'Epic Marketplace. Uno studio può mescolare plugin sorgente e plugin binari senza configurare nulla.

Cartella ThirdParty

Qualsiasi percorso contenente ThirdParty/ è sempre tracciato, anche se una regola superiore lo ignorerebbe. È per convenzione Unreal: ThirdParty/ contiene tipicamente librerie precompilate (.lib, .dll, .so, .a) di cui la compilazione del progetto ha bisogno.

Plugins/MyPlugin/Source/ThirdParty/SomeLib/lib/Win64/SomeLib.lib

Anche se scrivi **/lib/ o *.lib nel tuo .uversionignore, questo file resta tracciato grazie alla regola implicita ThirdParty/.

Ricette comuni

Progetto con art sorgente esterno (Maya, Blender, ZBrush)

Se le tue sorgenti art (.blend, .mb, .zpr) vivono accanto al progetto UE, vuoi tracciarle ma forse non le loro cache:

# Sources d'art (à versionner)
ArtSource/

# Mais pas les caches Blender / Maya
**/blendcache_*/
**/cache/
**/temp/
**/*.blend1
**/*.mb~

Progetto con diverse mappe di test da non committare

# Maps de test temporaires (chacun les sien sur son disque)
Content/Maps/Test_*.umap
Content/Maps/Test_*.uasset

Tracciare un binario specifico nonostante una regola generica

Non esistendo la negazione !, non si può escludere globalmente *.exe/*.dll e poi reincludere un binario. Colloca piuttosto i tuoi artefatti usa e getta sotto una cartella ignorata (ad es. Intermediate/) e tieni lo strumento da tracciare fuori dai pattern di esclusione. Alternativa Unreal: le librerie di build appartengono a ThirdParty/, che è sempre tracciato automaticamente.

Ignorare le note personali

# Chacun ses notes
notes.md
TODO.txt
.scratch/

Progetto multipiattaforma con pacchetti intermedi

# Packagés (publish via le client, pas dans le repo)
Packages/
Saved/StagedBuilds/

# Caches de cook par plateforme
Saved/Cooked/
Build/Win64/
Build/Mac/
Build/Linux/

Testare un file

Per verificare se un percorso verrà ignorato dal client prima di committare, usa la CLI:

$ uversion status MaybeIgnored/File.uasset
# Si le fichier apparaît dans la sortie → il est tracké
# S'il n'apparaît pas (et qu'il existe sur disque) → il est ignoré

Oppure, più direttamente, in modalità JSON con un filtro jq:

$ uversion status --json | jq '.files[] | select(.path == "MaybeIgnored/File.uasset")'

Insidie comuni

Slash finale = cartella, senza slash = ambiguo

foo ignora sia il file foo sia la cartella foo/. foo/ ignora solo la cartella. Se vuoi essere preciso, metti lo slash finale per le cartelle.

Sensibile alle maiuscole

I pattern fanno distinzione tra maiuscole e minuscole. Content/ non corrisponde a content/. Poiché Windows è insensibile alle maiuscole lato FS, puoi ritrovarti con collisioni silenziose se uno sviluppatore su Windows lo chiama Content/ e un altro content/. Standardizza su Content/.

Nessuna reinclusione (!)

Scrivere !Saved/Config/Foo.ini non reinclude nulla: la negazione non è supportata, la riga viene presa come un pattern letterale. Per conservare una sottocartella, ignora solo i sottoalberi da escludere (ad es. Saved/Logs/, Saved/Backup/) invece di tutto Saved/.

Pattern troppo ampi

*.zip ignora ogni .zip del workspace, compresi asset di gioco deliberatamente nominati .zip (raro, ma capita nei giochi di avventura / file di dati). Preferisci pattern più specifici: dist/*.zip, Releases/*.zip, ecc.

Modificare .uversionignore non influisce sui file già committati

Come git, aggiungere un pattern a .uversionignore non fa sparire i file già tracciati. Devi rimuoverli esplicitamente tramite il client desktop (Mark for delete + checkin) se vuoi toglierli dal repo.