.uversionignore

Einführung

Die Datei .uversionignore im Wurzelverzeichnis des Workspace definiert die Dateien und Ordner, die der Client niemals tracken, hochladen oder in Commits aufnehmen soll. Syntax im Stil von .gitignore (eine Teilmenge: Kommentare, mit / endende Ordnermuster sowie Namens-/Erweiterungs-Globs), kompiliert von globset. Es ist kein vollständiges gitignore: Negation mit ! und Verankerung werden nicht unterstützt. Einige Unreal-Engine-spezifische Regeln sind weiter unten dokumentiert.

Die Datei wird beim clone automatisch vom Desktop-Client mit einer Standard-UE5-Vorlage erstellt. Sie können sie anschließend an Ihr Projekt anpassen.

Die Datei wird selbst getrackt: Wenn Sie sie bearbeiten und committen, übernehmen Ihre Mitarbeiter Ihre Änderungen beim nächsten Sync. Das ist beabsichtigt: Das gesamte Studio hat dieselben Ausschlussregeln.

Syntax

Eine Regel pro Zeile. Leere Zeilen und Zeilen, die mit # beginnen, werden ignoriert (Kommentare).

Grundmuster

Platzhalter

Keine Negation (!)

Anders als bei .gitignore unterstützt uVersion das Präfix ! zum Wiedereinschließen einer Datei nicht. Eine mit ! beginnende Zeile wird als wörtliches Muster behandelt, nicht als Ausnahme. Das erneute Tracken von Dateien in einem ignorierten Ordner geschieht nur über die automatischen Regeln: die ThirdParty-Ausnahme und das Whitelisting der Binaries/ installierter Plugins (siehe unten).

Kommentare

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

Ein # in der Mitte einer Zeile ist kein Kommentar: Es ist Teil des Musters. Nur ein # am Zeilenanfang (nach optionalem Leerraum) leitet einen Kommentar ein.

Regel-Vorrang

Die Reihenfolge der Zeilen in der Datei spielt keine Rolle: Alle Muster werden in ein einziges GlobSet kompiliert, und ein Pfad wird ignoriert, sobald er auf eines davon passt. Die Entscheidung folgt einem festen Vorrang in dieser Reihenfolge:

1. Reservierter Pfad Plugins/uVersion: immer ignoriert (vom Tool verwalteter Ordner, Binärverteilung), selbst wenn eine Regel versuchen würde, ihn einzuschließen.
2. ThirdParty-Komponente: Wenn ein Pfadsegment exakt ThirdParty heißt, wird die Datei nie ignoriert.
3. Whitelisted Plugin-Präfix (Binaries/ eines installierten Plugins): nie ignoriert.
4. Andernfalls: Der Pfad wird ignoriert, wenn er auf ein Muster der Datei passt.

Standard-UE5-Vorlage

Hier ist genau das, was der Desktop-Client beim clone in einem UE5-Workspace erzeugt:

# 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

Sie können dieser Datei eigene Regeln hinzufügen. Denken Sie daran, sie zu committen, damit das gesamte Studio dieselben Ausschlüsse hat.

Plugins

Reservierter Ordner Plugins/uVersion

Der Ordner Plugins/uVersion (das uVersion-Plugin selbst) wird in jeder Tiefe immer ignoriert, und diese Regel hat Vorrang vor allem anderen. Er wird vom Desktop-Client verwaltet (Binärverteilung) und darf niemals committet werden. Benachbarte Ordner wie Plugins/uVersionExtras sind davon nicht betroffen.

uVersion wendet außerdem eine intelligente Logik für andere Plugins an, ohne dass Sie etwas in die Datei schreiben müssen:

• Wenn ein Plugin in seiner .uplugin "Installed": true hat und keinen Source/-Ordner besitzt (rein binäres Plugin, Marketplace-Art) → werden seine Binaries/ gewhitelistet und somit getrackt. Das ist korrekt: Bei einem Binär-Plugin sind die kompilierten .dll-Dateien das Plugin.
• Wenn das Plugin einen Source/-Ordner hat (neu kompilierbar) oder kein "Installed": true besitzt → werden seine Binaries/ und Intermediate/ wie beim Hauptprojekt ignoriert (Binärdateien sind beim Build neu erzeugte Artefakte).

Diese Logik erspart es, Ausnahmen für kommerzielle Plugins, die aus dem Epic Marketplace heruntergeladen wurden, manuell zu pflegen. Ein Studio kann Quell-Plugins und Binär-Plugins mischen, ohne irgendetwas zu konfigurieren.

ThirdParty-Ordner

Jeder Pfad, der ThirdParty/ enthält, wird immer getrackt, selbst wenn eine übergeordnete Regel ihn ignorieren würde. Das folgt der Unreal-Konvention: ThirdParty/ enthält typischerweise vorkompilierte Bibliotheken (.lib, .dll, .so, .a), die die Kompilierung des Projekts benötigt.

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

Selbst wenn Sie **/lib/ oder *.lib in Ihre .uversionignore schreiben, bleibt diese Datei dank der impliziten Regel ThirdParty/ getrackt.

Gängige Rezepte

Projekt mit externen Art-Quelldateien (Maya, Blender, ZBrush)

Wenn Ihre Art-Quelldateien (.blend, .mb, .zpr) neben dem UE-Projekt liegen, möchten Sie sie tracken, vielleicht aber nicht ihre Caches:

# Sources d'art (à versionner)
ArtSource/

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

Projekt mit mehreren Testkarten, die nicht committet werden sollen

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

Eine bestimmte Binärdatei trotz einer generischen Regel tracken

Da es keine Negation ! gibt, kann man nicht global *.exe/*.dll ausschließen und dann eine Binärdatei wieder einschließen. Legen Sie stattdessen Ihre Wegwerf-Artefakte in einen ignorierten Ordner (z. B. Intermediate/) und halten Sie das zu trackende Tool außerhalb der Ausschlussmuster. Unreal-Alternative: Build-Bibliotheken gehören in ThirdParty/, das immer automatisch getrackt wird.

Persönliche Notizen ignorieren

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

Plattformübergreifendes Projekt mit Zwischen-Paketen

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

Eine Datei testen

Um vor dem Commit zu prüfen, ob ein Pfad vom Client ignoriert wird, verwenden Sie die 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é

Oder direkter, im JSON-Modus mit einem jq-Filter:

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

Häufige Stolperfallen

Abschließender Schrägstrich = Ordner, ohne Schrägstrich = mehrdeutig

foo ignoriert sowohl die Datei foo als auch den Ordner foo/. foo/ ignoriert nur den Ordner. Wenn Sie präzise sein möchten, setzen Sie den abschließenden Schrägstrich für Ordner.

Groß-/Kleinschreibung beachten

Muster beachten die Groß-/Kleinschreibung. Content/ passt nicht auf content/. Da Windows auf FS-Seite Groß-/Kleinschreibung ignoriert, können stille Kollisionen entstehen, wenn ein Entwickler unter Windows Content/ und ein anderer content/ benennt. Standardisieren Sie auf Content/.

Keine Wiedereinschließung (!)

!Saved/Config/Foo.ini zu schreiben schließt nichts wieder ein: Negation wird nicht unterstützt, die Zeile wird als wörtliches Muster genommen. Um einen Unterordner zu behalten, ignorieren Sie nur die auszuschließenden Teilbäume (z. B. Saved/Logs/, Saved/Backup/) statt des gesamten Saved/.

Zu breite Muster

*.zip ignoriert jede .zip im Workspace, einschließlich absichtlich .zip benannter Spiel-Assets (selten, kommt aber bei Adventure-Spielen / Datendateien vor). Bevorzugen Sie spezifischere Muster: dist/*.zip, Releases/*.zip usw.

Das Bearbeiten von .uversionignore betrifft bereits committete Dateien nicht

Wie bei git lässt das Hinzufügen eines Musters zu .uversionignore bereits getrackte Dateien nicht verschwinden. Sie müssen sie explizit über den Desktop-Client (Mark for delete + checkin) entfernen, wenn Sie sie aus dem Repo nehmen möchten.