Wiki

.uversionignore

gitignore-artige Syntax zum Ausschließen von Dateien vom uVersion-Tracking. UE5-Standardwerte inklusive, Rezepte für gängige Setups.

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

Muster	Wirkung
`foo.txt`	Jede Datei mit dem Namen `foo.txt` auf jeder Ebene des Baums
`foo/`	Alle Ordner mit dem Namen `foo` und ihr Inhalt, auf jeder Ebene (Ordnermuster greifen immer in jeder Tiefe)
`foo`	Jede Datei ODER jeder Ordner mit dem Namen `foo` auf jeder Ebene (ohne abschließenden Schrägstrich)

Platzhalter

Muster	Wirkung
`*.tmp`	Alle `.tmp`-Dateien auf jeder Ebene
`*.{tmp,bak,old}`	Klammer-Expansion: entspricht `.tmp` + `.bak` + `*.old`
`foo*`	Jede Datei oder jeder Ordner, dessen Name mit `foo` beginnt
`?ile.txt`	`?` trifft genau ein Zeichen: `file.txt`, `pile.txt` usw.
`[abc].txt`	Zeichenklasse: `a.txt`, `b.txt`, `c.txt`
`**/build/`	Rekursiv: jeder `build/`-Ordner auf jeder Ebene (entspricht `build/`)
`Content/**/Tmp/`	Rekursiv in der Mitte: jeder `Tmp/`-Ordner irgendwo unterhalb von `Content/`
`Content/**`	Alles unter `Content/`, in jeder Tiefe

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:

Reservierter Pfad Plugins/uVersion: immer ignoriert (vom Tool verwalteter Ordner, als Binärdatei verteilt), selbst wenn eine Regel versuchen würde, ihn einzuschließen.
Segment ThirdParty: Wenn ein Pfadsegment exakt ThirdParty heißt, wird die Datei nie ignoriert. Siehe ThirdParty-Ordner.
Standardmäßig zugelassenes Plugin-Präfix (das Binaries/ eines installierten Plugins ohne Quellcode): nie ignoriert.
Andernfalls: Der Pfad wird ignoriert, wenn er auf ein Muster der Datei passt.

Die ersten drei Schritte sind endgültige Entscheidungen: Sobald einer von ihnen greift, wird der nächste nicht ausgewertet, und Ihre Muster werden gar nicht herangezogen. Deshalb lässt sich keiner von ihnen durch eine präzisere Regel "aushebeln".

Standard-UE5-Vorlage

Hier ist Zeile für Zeile, was der Desktop-Client beim clone in einem UE5-Workspace schreibt. Wenn Sie diesen Block von Hand in ein bestehendes Projekt kopieren, kopieren Sie ihn vollständig: Die Abschnitte "IDE" und "Linux-Projektgenerierung" werden am häufigsten vergessen, und ihr Fehlen führt dazu, dass bei jedem Build neu erzeugte Projektdateien getrackt werden, die dann bei allen zu Konflikten führen.

# 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

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, dessen Segment ThirdParty heißt, wird immer getrackt, welche Regel ihn auch bezeichnen würde. Das ist eine Unreal-Konvention: ThirdParty enthält die vorkompilierten Bibliotheken (.lib, .dll, .so, .a), die die Kompilierung des Projekts benötigt. Sie auszuschließen würde den Build bei all Ihren Teamkollegen kaputtmachen.

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

Selbst wenn Sie **/lib/, *.lib oder *.dll in Ihre .uversionignore schreiben, bleibt diese Datei getrackt.

Diese Ausnahme ist bedingungslos: keine Regel kann einen ThirdParty-Pfad ignorieren

Es geht nicht um Vorrang zwischen Regeln, bei dem die präzisere gewänne. Der Test „Enthält dieser Pfad ein ThirdParty-Segment?" wird vor jedem Lesen Ihrer Muster ausgewertet, und wenn er mit Ja antwortet, wird die Datei als getrackt deklariert und die Auswertung endet dort. Ihre Regeln werden nie herangezogen.

Es gibt also keine „explizite Ausnahmegenehmigung", um einen ThirdParty-Teilbaum auszuschließen: keine Regel, wie präzise auch immer, kann das erreichen. Wenn Sie einen solchen Ordner wirklich beiseitelassen müssen, ist der einzige Weg, ihn umzubenennen oder aus einer ThirdParty-Struktur herauszuverschieben.

Nur eine einzige Sache übertrumpft diese Ausnahme: der reservierte Ordner Plugins/uVersion, der auch unter ThirdParty ignoriert bleibt.

Das Segment muss exakt ThirdParty sein

Der Vergleich betrifft ein ganzes Pfadsegment, nicht ein Namenspräfix. Ein Ordner namens ThirdPartyLibs, ThirdParty_Old oder MyThirdParty ist nicht betroffen: Sein Inhalt unterliegt Ihren Regeln wie jede andere Datei, und eine *.dll-Regel schließt ihn aus.

Das ist eine häufige Überraschungsquelle: Source/ThirdParty/Lib/x.dll wird getrackt, Source/ThirdPartyLibs/Lib/x.dll nicht. Wenn Sie feststellen, dass eine Bibliothek nicht gesendet wird, prüfen Sie zuerst die genaue Schreibweise des Ordners.

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.