.uversionignore

Introduction

Le fichier .uversionignore à la racine du workspace définit les fichiers et dossiers que le client ne doit jamais tracker, uploader, ou inclure dans les commits. Syntaxe de style .gitignore (un sous-ensemble : commentaires, patterns de dossier terminés par /, et globs de nom/extension), compilée par globset. Ce n'est pas un gitignore complet : la négation ! et l'ancrage ne sont pas supportés. Quelques règles spécifiques à Unreal Engine sont documentées plus bas.

Le fichier est créé automatiquement par le client desktop au moment du clone avec un template UE5 par défaut. Vous pouvez l'éditer ensuite pour adapter à votre projet.

Le fichier est lui-même tracké : si vous l'éditez et le commitez, vos collaborateurs récupèrent vos changements au prochain sync. C'est intentionnel : tout le studio a les mêmes règles d'exclusion.

Syntaxe

Une règle par ligne. Lignes vides et lignes commençant par # sont ignorées (commentaires).

Patterns de base

Wildcards

Pas de négation (!)

Contrairement à .gitignore, uVersion ne supporte pas le préfixe ! pour re-inclure un fichier. Une ligne commençant par ! est traitée comme un pattern littéral, pas comme une exception. Le re-tracking de fichiers dans un dossier ignoré se fait uniquement via les règles automatiques : la carve-out ThirdParty et le whitelist des Binaries/ de plugins installés (voir plus bas).

Commentaires

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

Un # au milieu d'une ligne n'est pas un commentaire : il fait partie du pattern. Seul # en début de ligne (après whitespace optionnel) commente.

Précédence des règles

L'ordre des lignes dans le fichier n'a aucune importance : tous les patterns sont compilés dans un unique GlobSet et un chemin est ignoré dès qu'il matche l'un d'eux. La décision suit une précédence fixe, dans cet ordre :

1. Chemin réservé Plugins/uVersion : toujours ignoré (dossier géré par l'outil, distribution binaire), même si une règle tenterait de l'inclure.
2. Composant ThirdParty : si un segment du chemin s'appelle exactement ThirdParty, le fichier n'est jamais ignoré.
3. Préfixe de plugin whitelisté (Binaries/ d'un plugin installé) : jamais ignoré.
4. Sinon : le chemin est ignoré s'il matche un pattern du fichier.

Template UE5 par défaut

Voici exactement ce que le client desktop génère au moment du clone dans 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

Vous pouvez ajouter vos propres règles à ce fichier. Pensez à le commiter pour que tout le studio ait les mêmes exclusions.

Plugins

Dossier réservé Plugins/uVersion

Le dossier Plugins/uVersion (le plugin uVersion lui-même) est toujours ignoré, à n'importe quelle profondeur, et cette règle l'emporte sur tout le reste. Il est géré par le client desktop (distribution binaire) et ne doit jamais être commité. Les dossiers voisins comme Plugins/uVersionExtras ne sont pas concernés.

uVersion applique aussi une logique smart pour les autres plugins, sans rien à écrire dans le fichier :

• Si un plugin a "Installed": true dans son .uplugin et n'a pas de dossier Source/ (plugin purement binaire, type Marketplace) → ses Binaries/ sont whitelisted, donc trackés. C'est normal : pour un plugin binaire, les .dll compilées sont le plugin.
• Si le plugin a un dossier Source/ (recompilable) ou n'a pas "Installed": true → ses Binaries/ et Intermediate/ sont ignorés comme pour le projet principal (les binaires sont des artefacts régénérés au build).

Cette logique évite de devoir maintenir manuellement les exceptions pour les plugins commerciaux téléchargés depuis le Marketplace Epic. Un studio peut mélanger plugins source et plugins binaires sans configurer quoi que ce soit.

Dossier ThirdParty

Tout chemin contenant ThirdParty/ est toujours tracké, même si une règle parente l'ignorerait. C'est par convention Unreal : ThirdParty/ contient typiquement des libs précompilées (.lib, .dll, .so, .a) dont la compilation du projet a besoin.

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

Même si vous écrivez **/lib/ ou *.lib dans votre .uversionignore, ce fichier reste tracké grâce à la règle implicite ThirdParty/.

Recettes courantes

Projet avec art source externe (Maya, Blender, ZBrush)

Si vos sources d'art (.blend, .mb, .zpr) vivent à côté du projet UE, vous voulez les tracker mais peut-être pas leurs caches :

# Sources d'art (à versionner)
ArtSource/

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

Projet avec plusieurs maps de test à ne pas committer

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

Tracker un binaire spécifique malgré une règle générique

La négation ! n'existant pas, on ne peut pas exclure globalement *.exe/*.dll puis re-inclure un binaire. Placez plutôt vos artefacts jetables sous un dossier ignoré (par ex. Intermediate/) et gardez l'outil à tracker en dehors des patterns d'exclusion. Alternative Unreal : les libs de build appartiennent à ThirdParty/, qui est toujours tracké automatiquement.

Ignorer les notes personnelles

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

Projet multi-plateforme avec packagés intermédiaires

# 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/

Tester un fichier

Pour vérifier si un chemin sera ignoré ou non par le client avant de commit, utilisez le 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é

Ou, plus directement, en mode JSON avec un filtre jq :

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

Pièges courants

Slash final = dossier, sans slash = ambigu

foo ignore à la fois le fichier foo et le dossier foo/. foo/ ignore uniquement le dossier. Si vous voulez être précis, mettez le slash final pour les dossiers.

Casse sensible

Les patterns sont sensibles à la casse. Content/ ne matche pas content/. Comme Windows est insensible à la casse côté FS, vous pouvez vous retrouver avec des collisions silencieuses si un dev sous Windows nomme Content/ et un autre content/. Standardisez sur Content/.

Pas de re-inclusion (!)

Écrire !Saved/Config/Foo.ini ne re-inclut rien : la négation n'est pas supportée, la ligne est prise comme un pattern littéral. Pour garder un sous-dossier, n'ignorez que les sous-arbres à exclure (par ex. Saved/Logs/, Saved/Backup/) au lieu de tout Saved/.

Patterns trop larges

*.zip ignore tout .zip du workspace, y compris des assets de jeu volontairement nommés .zip (rare, mais arrive en jeu d'aventure / data files). Préférez des patterns plus spécifiques : dist/*.zip, Releases/*.zip, etc.

Modifier .uversionignore n'affecte pas les fichiers déjà commitez

Comme git, ajouter un pattern à .uversionignore ne fait pas disparaître les fichiers déjà trackés. Vous devez les supprimer explicitement via le client desktop (Mark for delete + checkin) si vous voulez les retirer du repo.