.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

Pattern	Effet
foo.txt	Tout fichier nommé foo.txt à n'importe quel niveau de l'arborescence
foo/	Tous les dossiers nommés foo et leur contenu, à n'importe quel niveau (les patterns de dossier matchent toujours à toute profondeur)
foo	Tout fichier OU dossier nommé foo à n'importe quel niveau (sans le slash final)

Wildcards

Pattern	Effet
*.tmp	Tous les fichiers .tmp à n'importe quel niveau
*.{tmp,bak,old}	Brace expansion : équivaut à *.tmp + *.bak + *.old
foo*	Tout fichier ou dossier dont le nom commence par foo
?ile.txt	Le ? match exactement un caractère : file.txt, pile.txt, etc.
[abc].txt	Classe de caractères : a.txt, b.txt, c.txt
**/build/	Récursif : tout dossier build/ à n'importe quel niveau (équivalent à build/)
Content/**/Tmp/	Récursif au milieu : tout dossier Tmp/ situé quelque part sous Content/
Content/**	Tout sous Content/, à n'importe quelle profondeur

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, distribué sous forme binaire), même si une règle tentait de l'inclure.
2. Segment ThirdParty : si un segment du chemin s'appelle exactement ThirdParty, le fichier n'est jamais ignoré. Voir Dossier ThirdParty.
3. Préfixe de plugin autorisé d'office (le Binaries/ d'un plugin installé sans code source) : jamais ignoré.
4. Sinon : le chemin est ignoré s'il correspond à l'un des motifs du fichier.

Les trois premières étapes sont des décisions définitives : dès que l'une d'elles s'applique, la suivante n'est pas évaluée, et vos motifs ne sont pas consultés du tout. C'est pourquoi on ne peut pas « contrer » l'une d'elles par une règle plus précise.

Template UE5 par défaut

Voici, à la ligne près, ce que le client desktop écrit au moment du clone dans un workspace UE5. Si vous recopiez ce bloc à la main dans un projet existant, recopiez-le en entier : les sections « IDE » et « génération de projet Linux » sont celles qu'on oublie le plus souvent, et leur absence fait suivre des fichiers de projet régénérés à chaque build, qui se retrouvent alors en conflit chez tout le monde.

# 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
*.slnx
*.xcworkspace/
*.xcodeproj/
*.code-workspace
*.suo
*.sdf
*.opensdf
*.opendb
*.ncb
*.user

# Linux project generation (GenerateProjectFiles)
Makefile
.ignore

# 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 dont un segment s'appelle ThirdParty est toujours suivi, quelle que soit la règle qui le désignerait. C'est une convention Unreal : ThirdParty contient les bibliothèques précompilées (.lib, .dll, .so, .a) dont la compilation du projet a besoin. Les exclure casserait le build chez tous vos coéquipiers.

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

Même si vous écrivez **/lib/, *.lib ou *.dll dans votre .uversionignore, ce fichier reste suivi.

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à commités

Comme avec git, ajouter un motif à .uversionignore ne fait pas disparaître les fichiers déjà suivis : la règle ne s'applique qu'à ce qui n'est pas encore dans le dépôt. Pour les retirer, il faut les supprimer explicitement depuis le client desktop, en les marquant pour suppression puis en validant.