Wiki

CLI uversion

Vollständige Referenz der uVersion-CLI: alle Befehle, Flags, Beispiele, JSON output, Exit-Codes.

Die uversion-Binärdatei deckt dieselben Versionierungsoperationen ab wie der Desktop-Client, zusätzlich mit einer von einem Programm verwertbaren --json-Ausgabe für die Automatisierung: Continuous Integration, Onboarding-Skripte, hauseigenes Tooling. Diese Seite richtet sich an Entwickler und Studio-Administratoren.

Installation

Unter Windows ist die Binärdatei uversion.exe im Installer des Desktop-Clients enthalten und wird automatisch zum Benutzer-PATH hinzugefügt (%LOCALAPPDATA%\uVersion). Der PATH-Eintrag wird bei jedem Update entdoppelt und bei der Deinstallation entfernt. Öffnen Sie ein neues Terminal und tippen Sie:

uversion --help

Unter macOS geschieht dies automatisch: Beim ersten Start legt der Desktop-Client einen Link auf die eingebettete Binärdatei unter ~/.local/bin/uversion an und stellt sicher, dass dieser Ordner im PATH liegt (über ~/.zprofile). Starten Sie die App einmal, öffnen Sie ein neues Terminal, und der Befehl uversion steht zur Verfügung. Um es von Hand an einen anderen Ort im PATH zu tun:

ln -s /Applications/uVersion.app/Contents/Resources/uversion /usr/local/bin/uversion

Unter Linux geschieht dies ebenfalls automatisch, genau wie unter macOS. Der Desktop-Client wird als AppImage verteilt, und dieses AppImage enthält die uversion-Binärdatei. Beim ersten Start legt die App sie unter ~/.local/bin/uversion ab und stellt sicher, dass dieser Ordner im PATH liegt. Starten Sie die App einmal, öffnen Sie ein neues Terminal, und der Befehl steht zur Verfügung:

uversion --help

Sie müssen nichts kompilieren. Unter Linux wird der Desktop-Client ausschließlich als AppImage verteilt, und es ist dieses AppImage, das die CLI mitbringt. Um die Binärdatei anderswo im PATH abzulegen, kopieren Sie sie aus ~/.local/bin:

sudo cp ~/.local/bin/uversion /usr/local/bin/uversion

Um die installierte Version zu prüfen:

$ uversion --version

Spickzettel: alle Befehle

Die vollständige Menge der verfügbaren Befehle, in der Reihenfolge, in der man ihnen typischerweise begegnet:

Befehl	Was er tut
`uversion login <url> -u <user>`	An einem Server authentifizieren
`uversion logout`	Die gespeicherten Anmeldedaten löschen
`uversion repos`	Zugängliche Repositories auflisten
`uversion clone <repo> [path]`	Ein Repository klonen
`uversion info`	Workspace-Zustand + aktuellen Benutzer anzeigen
`uversion status [paths...]`	Geänderte / neue / gelöschte / gesperrte Dateien ansehen
`uversion checkout <paths...>`	Dateien zum Bearbeiten reservieren (setzt eine Sperre)
`uversion checkin <paths...> -m "..."`	Änderungen hochladen und einchecken
`uversion revert <paths...>`	Lokale Änderungen verwerfen und die Sperren freigeben
`uversion sync`	Änderungen vom Server holen (ganzes Repository)
`uversion content <path> --revision <n>`	Eine bestimmte Version einer Datei herunterladen
`uversion log`	Commit-Verlauf
`uversion lock list`	Alle Sperren des Repositorys ansehen
`uversion lock release <paths...>`	Eine Sperre freigeben, ohne die Datei anzurühren
`uversion lock heartbeat`	Melden, dass Ihre Sperren noch in Gebrauch sind (zur Überwachung)
`uversion trust <url>`	Den Fingerabdruck des selbstsignierten Zertifikats eines Servers merken (interaktiv; `--yes` zum Skripten)
`uversion mistrust <url>`	Den gemerkten Fingerabdruck eines Servers vergessen
`uversion trusted`	Server auflisten, deren Fingerabdruck gemerkt ist

Alle Befehle außer uversion content akzeptieren --json, das die lesbare Anzeige durch eine von einem Programm verwertbare Ausgabe ersetzt (siehe JSON output). Alle akzeptieren --help für die Details der Optionen.

checkout, checkin und revert akzeptieren außerdem --paths-file <fichier>, unverzichtbar, sobald man im Maßstab eines Unreal-Projekts arbeitet. Siehe Umfangreiche Pfadlisten.

Authentifizierung

`uversion login`

Authentifiziert an einem uVersion-Server. Der Server übergibt ein Sitzungstoken (ein JWT, für JSON Web Token), das die CLI im Passwortmanager des Systems ablegt: der Anmeldeinformationsverwaltung unter Windows, dem Schlüsselbund unter macOS, libsecret unter Linux. Dieses Token wird mit dem Desktop-Client, dem Unreal-Plugin und dem Rider-Plugin geteilt: Sich auf einer Seite anzumelden meldet die anderen an, und sich abzumelden meldet sie alle ab.

uversion login <url_serveur> -u <utilisateur> [-p <mot_de_passe>]

Option	Beschreibung
`-u, --username`	Benutzername
`-p, --password`	Nicht empfohlen. Siehe den Kasten unten. Wird die Option weggelassen, liest die CLI die Umgebungsvariable `UVERSION_PASSWORD`, und andernfalls fragt sie das Passwort interaktiv ab, ohne Anzeige auf dem Bildschirm.

Um eine Anmeldung zu skripten, verwenden Sie UVERSION_PASSWORD, niemals -p

Auf einem Mehrbenutzersystem ist die Befehlszeile jedes Prozesses für die anderen Konten der Maschine lesbar: ps unter Linux und macOS, der Task-Manager oder wmic unter Windows. Ein als Argument übergebenes Passwort erscheint dort im Klartext, auch wenn es aus einer Variablen stammt, da die Shell diese vor dem Start des Programms durch ihren Wert ersetzt. Es landet außerdem im Shell-Verlauf und häufig in den Protokollen der Continuous-Integration-Kette.

Die CLI liest UVERSION_PASSWORD genau, um dies zu vermeiden, und zeigt eine Warnung auf der Standardfehlerausgabe an, wenn -p verwendet wird.

Beispiele:

$ uversion login https://uversion.mygamestudio.com -u alice
Password:
Logged in as alice (artist)

# Sur un serveur de studio, en interne. Le port par défaut est 8443, en HTTPS.
$ uversion login https://192.168.1.100:8443 -u bob
Password:
Logged in as bob (programmer)

# Compte d'intégration continue : le mot de passe passe par l'environnement,
# jamais par la ligne de commande.
$ export UVERSION_PASSWORD="$SECRET_FROM_VAULT"
$ uversion login "$UV_SERVER" -u ci-nightly
Logged in as ci-nightly (programmer)

Bei der ersten Verbindung zu einem Server, der ein selbstsigniertes Zertifikat vorlegt, zeigt die CLI den Fingerabdruck des Zertifikats an und bittet Sie, ihn zu bestätigen, und merkt ihn sich dann. Das ist das Prinzip des Vertrauens beim ersten Kontakt, dasselbe wie bei SSH: Man akzeptiert eine Identität einmal, und jede spätere Vorlage einer anderen Identität wird gemeldet. Ändert sich der Fingerabdruck, verweigert die CLI die Verbindung und warnt Sie: Es ist entweder eine legitime Erneuerung des Zertifikats oder ein Abfangen Ihres Verkehrs durch einen Dritten. Der bewusste Schritt ist dann uversion mistrust <url>, gefolgt von einer neuen Verbindung.

`uversion logout`

Löscht das Token aus dem Passwortmanager des Systems und macht serverseitig alle Sitzungen dieses Kontos ungültig. Da das Token geteilt wird, meldet dies auch den Desktop-Client, das Unreal-Plugin und das Rider-Plugin ab, auf allen Ihren Maschinen.

$ uversion logout
Logged out (alice)

$ uversion logout       # si aucune session n'était ouverte
Already logged out

Welches Konto handelt? Das des Workspace, nicht das zuletzt angemeldete

Das ist der Punkt, der am meisten überrascht, und man sollte ihn kennen, bevor man irgendetwas skriptet: Die verwendete Identität ist nicht die der letzten Anmeldung, sondern die des Workspace, in dem Sie sich befinden.

Ein Workspace ist ein geklonter Ordner, erkennbar an seinem Unterordner .uversion. Die Datei .uversion/config.toml darin verzeichnet den Server und das Eigentümerkonto:

[repository]
id = "1"
name = "hero-rpg"
server_url = "https://uversion.mygamestudio.com"

[workspace]
id = "..."
name = "alice-cli"
owner = "alice"
last_synced_revision = 42

Sobald Sie sich in einem Workspace befinden, sind server_url und owner maßgeblich: status, checkout, checkin, revert, sync, log, content, lock und info authentifizieren als owner, gegen server_url.

Nur login, logout, repos und clone verwenden die zwischen allen Workspaces geteilte Konfiguration (unter Windows %APPDATA%/uversion/uVersion/config/config.toml), die dem aktiven Konto des Desktop-Clients folgt.

Warum. Ein und dieselbe Maschine dient oft mehreren Konten, zum Beispiel einem Freelancer, der für zwei Studios arbeitet. Ohne diese Regel würden alle Workspaces unter dem gerade aktiven Konto handeln: Ein von alice geklonter, aber genutzter Ordner, während bob aktiv ist, würde seine Sperren im Namen von bob setzen, seine eigenen Dateien als „von jemand anderem gesperrt" sehen und seine Uploads abgelehnt bekommen.

Um die Identität eines Workspace zu ändern, bearbeiten Sie das Feld owner in .uversion/config.toml und stellen Sie sicher, dass sich dieses Konto mindestens einmal auf dieser Maschine angemeldet hat (uversion login), damit sein Token vorhanden ist. Prüfen Sie danach mit uversion info, das das tatsächlich verwendete Konto anzeigt.

Bekannte Einschränkung: derselbe Benutzername auf zwei Servern

Das Token wird allein unter dem Benutzernamen abgelegt, ohne den Server. Existiert derselbe Name auf zwei verschiedenen uVersion-Servern, teilen sich beide ein und denselben Eintrag: Die Anmeldung am zweiten überschreibt das Token des ersten. Verwenden Sie unterschiedliche Namen, oder nutzen Sie von einer Maschine aus jeweils nur einen Server.

Repositories

`uversion repos`

Listet die Repositories auf, auf die das Konto Zugriff hat. Dieser Befehl verwendet die geteilte Konfiguration, nicht die eines Workspace: Er antwortet also für das Konto Ihrer letzten Anmeldung.

$ uversion repos
ID     Name                           Description
----------------------------------------------------------------------
1      hero-rpg                       Main RPG project
2      shared-assets                  Shared asset library
12     prototype-fps                  R&D prototype FPS

$ uversion repos          # si aucun dépôt n'est accessible
No repositories found

`uversion clone`

Holt ein Repository lokal. Wird der Pfad weggelassen, wird ein nach dem Repository benannter Ordner im aktuellen Verzeichnis erstellt. Das Klonen erstellt außerdem den Unterordner .uversion, der den Ordner zu einem Workspace macht und den Server und das Eigentümerkonto verzeichnet.

Die Übertragung wendet Deduplizierung an: Der Inhalt wird in Blöcke zerlegt, und ein bereits vorhandener Block wird nur einmal gespeichert, auch wenn er in mehreren Dateien auftaucht. Deshalb ist der auf der Festplatte belegte Platz oft deutlich geringer als das heruntergeladene Volumen.

uversion clone <repo_name_or_id> [local_path]

Beispiele:

$ uversion clone hero-rpg
Cloning hero-rpg to ./hero-rpg...
✓ 8,432 files in 47s (14.2 GB downloaded, 6.1 GB on disk after dedup)

$ uversion clone hero-rpg D:\Projects\HeroRPG
$ uversion clone 1                              # par ID au lieu du nom

Dateien

`uversion status`

Zeigt den Zustand der Dateien des aktuellen Workspace: geändert, neu (untracked), gelöscht, von anderen gesperrt.

uversion status [paths...] [--json]

Beispiele:

$ uversion status
Modified:
  M  Content/Maps/MainLevel.umap (locked by alice)
New:
  A  Content/Textures/NewTexture.png
Deleted:
  D  Content/OldAsset.uasset
Locked by others:
  L  Content/Characters/Hero.uasset  (locked by bob)

1 modified, 1 new, 1 deleted, 1 locked by others

$ uversion status Content/Maps                  # filtre par dossier
$ uversion status --json | jq '.summary'        # extraction scriptable

`uversion checkout`

Setzt eine exklusive Sperre auf die Zieldateien und macht sie auf der Festplatte beschreibbar. Die getrackten Dateien sind schreibgeschützt, solange sie nicht reserviert sind: Das ist es, was verhindert, dass zwei Personen dasselbe Binär-Asset parallel bearbeiten.

uversion checkout <paths...> [--paths-file <fichier>] [--force] [--add] [--json]

Option	Beschreibung
`--paths-file`	Zusätzliche Pfade aus einer Datei lesen, einen pro Zeile. Siehe Umfangreiche Pfadlisten.
`--force`	Nimmt die Sperre, selbst wenn sie von jemand anderem gehalten wird. Beschränkt auf Konten, die die Fähigkeit `force_unlock` besitzen, also die Rollen `admin` und `lead`. Siehe unten.
`--add`	Erlaubt das Reservieren von Pfaden, die lokal noch nicht vorhanden sind, für neue Dateien.

Was --force wirklich tut

Die Option nimmt die Sperre eines anderen. Sie wird durch die Fähigkeit force_unlock geschützt, die von den Rollen admin und lead gehalten wird. Ein Konto, das sie nicht hat, erhält eine ausdrückliche Ablehnung, mit dem einzuschlagenden Weg: einen Administrator darum bitten, oder die Schaltfläche „Freigabe anfordern" des Desktop-Clients verwenden, die die betroffene Person benachrichtigt.

Wenn eine Übernahme tatsächlich stattgefunden hat, wird sie ins Audit-Protokoll eingetragen, mit den betroffenen Pfaden und den Namen der Personen, denen die Sperren genommen wurden. Nichts wird geschrieben, wenn die Option zwar vorhanden war, aber keine fremde Sperre den Besitzer gewechselt hat: In Skripten ist das Flag oft grundsätzlich gesetzt, und ein mit gegenstandslosen Ereignissen gefülltes Protokoll ist ein Protokoll, das niemand liest.

Beispiele:

$ uversion checkout Content/Maps/MainLevel.umap
✓ Lock acquired: Content/Maps/MainLevel.umap

$ uversion checkout Content/Characters/Hero.uasset Content/Characters/Villain.uasset
✓ Lock acquired: Content/Characters/Hero.uasset
✓ Lock acquired: Content/Characters/Villain.uasset

# Fichier déjà réservé par bob
$ uversion checkout Content/Maps/MainLevel.umap
✗ File is locked (bob)

# Compte sans la capacité force_unlock
$ uversion checkout --force Content/Maps/MainLevel.umap
Error: Taking a lock held by another user requires the force_unlock capability
(admin or lead). Ask an administrator, or use Request Release to ask the holder.

# Compte admin ou lead : le vol passe, et il est tracé
$ uversion checkout --force Content/Maps/MainLevel.umap
✓ Lock acquired: Content/Maps/MainLevel.umap

`uversion checkin`

Lädt die geänderten Dateien hoch und checkt sie in einer einzigen Transaktion auf dem Server ein: entweder geht alles durch, oder nichts. Die Sperren werden bei Erfolg automatisch freigegeben.

uversion checkin [paths...] [--paths-file <fichier>] -m <message> [--all] [--json]

Option	Beschreibung
`-m, --message`	Commit-Nachricht. Erforderlich.
`-a, --all`	Alle geänderten Dateien des Workspace einbeziehen, nicht nur die als Argument übergebenen.
`--paths-file`	Zusätzliche Pfade aus einer Datei lesen, einen pro Zeile. Siehe Umfangreiche Pfadlisten.

Beispiele:

$ uversion checkin Content/Maps/MainLevel.umap -m "Fixed lighting in main level"
Validating 1 file...
✓ All validation rules passed
Uploading: [####################] 100% · 84 MB
✓ Committed as 7f3a9b1 (1 file, 84 MB uploaded, 0 deduped)

$ uversion checkin --all -m "Weekly art update"   # tout le workspace
$ uversion checkin Content/Characters/ -m "Updated character meshes"

`uversion revert`

Verwirft die lokalen Änderungen an einer oder mehreren Dateien, stellt die Serverversion wieder her und gibt die entsprechenden Sperren frei.

uversion revert <paths...> [--paths-file <fichier>] [--json]

Beispiele:

$ uversion revert Content/Maps/MainLevel.umap
✓ Reverted: Content/Maps/MainLevel.umap (lock released)

$ uversion revert Content/Characters/        # récursif par dossier

Umfangreiche Pfadlisten: `--paths-file`

checkout, checkin und revert akzeptieren --paths-file <fichier>: eine Textdatei mit einem Pfad pro Zeile. Die so gelesenen Pfade werden zu den als Argument übergebenen hinzugefügt, sie ersetzen sie nicht.

Wozu das dient. In einem Unreal-Projekt betrifft eine Operation häufig mehrere Tausend Dateien. Sie alle als Argumente zu übergeben stößt an eine Grenze des Systems: Unter Windows darf eine Befehlszeile 32.767 Zeichen nicht überschreiten, was etwa 500 Asset-Pfaden entspricht. Darüber hinaus scheitert der Befehl noch bevor er startet, mit einer Systemfehlermeldung, die nichts über das eigentliche Problem sagt. --paths-file beseitigt diese Grenze: Die Datei kann so viele enthalten, wie nötig.

Alle geänderten Dateien eines Ordners reservieren, gleich wie viele es sind:

$ uversion status --json \
    | jq -r '.files[] | select(.status == "modified") | .path' > /tmp/changed.txt
$ wc -l /tmp/changed.txt
3184 /tmp/changed.txt

$ uversion checkout --paths-file /tmp/changed.txt

Und dann genau denselben Stapel hochladen:

$ uversion checkin --paths-file /tmp/changed.txt -m "Import de la passe d'éclairage"

Unter Windows, in PowerShell:

PS> (uversion status --json | ConvertFrom-Json).files |
      Where-Object { $_.status -eq "modified" } |
      ForEach-Object { $_.path } |
      Set-Content -Encoding utf8 changed.txt

PS> uversion checkout --paths-file changed.txt

Es ist auch der Mechanismus, den das Rider-Plugin verwendet, um eine umfangreiche Änderungsmenge zu übergeben.

`uversion sync`

Lädt die neuesten Änderungen vom Server herunter und wendet sie auf den lokalen Workspace an.

uversion sync [--force] [--json]

Flag	Beschreibung
`-f, --force`	Vollständige Synchronisierung: lädt alle Dateien erneut herunter, nicht nur das Delta seit der letzten Synchronisierung. Nützlich bei einem beschädigten Workspace.

Beispiele:

$ uversion sync
Syncing from revision 41 → 47...
✓ 12 files updated, 3 added, 1 deleted (1.4 GB downloaded)

$ uversion sync --force                      # re-télécharge tout

`uversion content`

Lädt eine bestimmte Version einer Datei herunter, ohne den lokalen Workspace anzurühren. Nützlich zum Vergleichen, Archivieren oder um einen vergangenen Zustand abzurufen, ohne ein revert zu machen.

uversion content <path> [-r <numéro_de_révision>] [-o <fichier>]

--revision erwartet eine ganze Zahl, keinen Commit-Hash

Es ist die Revisionsnummer der Datei: ein Zähler, der bei ihrer ersten Version 1 ist, bei der zweiten 2, und so weiter. Einen Commit-Hash wie 6e2b8a0 zu übergeben lässt den Befehl bereits beim Parsen der Argumente scheitern.

Die Nummer lässt sich in uversion log --path <fichier> ablesen, wo jede Dateizeile sie in Klammern anzeigt. Wird --revision weggelassen, wird die neueste Version heruntergeladen.

Beispiele:

$ uversion content Content/Maps/MainLevel.umap --revision 12 --output ./snapshot.umap

$ uversion content Content/Characters/Hero.uasset -r 8 -o ./hero-v8.uasset

# Sans --output, le contenu est écrit sur la sortie standard
$ uversion content Config/DefaultEngine.ini -r 3 > DefaultEngine-v3.ini

Verlauf

`uversion log`

Commit-Verlauf des aktuellen Repositorys, optional nach Datei gefiltert.

uversion log [-n <limit>] [-p <path>] [--json]

Flag	Beschreibung
`-n, --limit`	Anzahl der anzuzeigenden Einträge (Standard: 20)
`-p, --path`	Nach Dateipfad filtern

Beispiele:

$ uversion log
commit 7f3a9b1c2d...
Author: alice
Date:   2026-05-15 08:30:00 UTC

    Fixed lighting in main level

    Content/Maps/MainLevel.umap (rev 12)

commit 6e2b8a0...
Author: bob
Date:   2026-05-14 17:22:00 UTC

    Hero pose pass

    Content/Characters/Hero.uasset (rev 8)
    Content/Characters/OldHero.uasset (deleted, rev 9)

$ uversion log -n 5                                  # 5 derniers commits
$ uversion log --path Content/Maps/MainLevel.umap    # historique d'un fichier

Eine mit deleted markierte Zeile ist eine Löschrevision: Sie trägt eine Nummer wie die anderen, hat aber keinen Inhalt zum Herunterladen.

Sperren

Eine Sperre läuft niemals ab

Sie hält, bis sie ausdrücklich freigegeben wird: durch uversion checkin, durch uversion revert, durch uversion lock release oder durch eine erzwungene Entsperrung durch einen Administrator. Es existiert kein automatisches Ablaufen, weder nach einer Stunde noch nach einem Monat. Eine reservierte und vergessene Datei bleibt es, bis jemand eingreift.

Folglich verlängert uversion lock heartbeat nichts. Dieser Befehl sagt nur „diese Sperren brauche ich noch", damit die Administratoren eine aktive Sperre von einer verlassenen unterscheiden können.

`uversion lock list`

Zeigt alle Sperren des aktuellen Repositorys an.

uversion lock list [--json]

Beispiele:

$ uversion lock list
File                                     User            Acquired
----------------------------------------------------------------------
Content/Maps/MainLevel.umap             alice           2026-05-15T08:42:11Z
Content/Characters/Hero.uasset          bob             2026-05-14T17:00:00Z
Content/UI/HUD.uasset                   alice           2026-05-15T09:15:00Z

Gibt es nichts anzuzeigen, schreibt der Befehl No active locks.

`uversion lock release`

Gibt eine oder mehrere Sperren frei, ohne den lokalen Inhalt der Datei anzurühren. Zu verwenden, um ein Asset „zurückzugeben", das man nicht geändert hat: versehentlich reserviert oder ohne Upload aufgegebene Arbeit.

uversion lock release <paths...> [--json]

Beispiele:

$ uversion lock release Content/Maps/MainLevel.umap
✓ Lock released: Content/Maps/MainLevel.umap

Dieser Befehl gibt nur Ihre eigenen Sperren frei. Um die eines anderen zu entfernen, muss man über die Administration gehen oder über uversion checkout --force, wenn Sie admin oder lead sind.

`uversion lock heartbeat`

Meldet, dass die vom aktuellen Konto gehaltenen Sperren noch in Gebrauch sind. Das verlängert sie nicht: Nichts läuft ab. Es ist ein Überwachungssignal, damit ein Administrator, der die Sperrliste durchsieht, sieht, welche noch aktiv sind. Im täglichen Arbeiten unnötig; nützlich für eine automatisierte Verarbeitung, die eine Datei stundenlang reserviert hält.

$ uversion lock heartbeat
3 lock(s) extended

$ uversion lock heartbeat        # si vous ne détenez aucun verrou
No locks to extend

Beispiel in Continuous Integration:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Zeigt das verwendete Konto und den Zustand des aktuellen Workspace an. Es ist der zuerst auszuführende Befehl, wenn sich etwas unerwartet verhält: Er zeigt, unter welcher Identität die CLI tatsächlich handelt, nämlich der des Workspace-Eigentümers und nicht zwingend der Ihrer letzten Anmeldung (siehe Welches Konto handelt?).

$ uversion info
User: alice (lead)

Repository: hero-rpg (id: 1)
Server:     https://uversion.mygamestudio.com
Workspace:  alice-cli (3f2a1c8e-...)
Local path: D:\Projects\HeroRPG
Last sync:  revision 42

Außerhalb eines Workspace oder ohne gültige Sitzung:

$ uversion info
User: not logged in

Workspace: not in a uVersion workspace

Der Befehl zählt die Dateien nicht und zeigt keine Zusammenfassung der Änderungen: Das ist die Aufgabe von uversion status.

JSON output

Alle Befehle außer content akzeptieren --json, das die lesbare Anzeige durch eine strukturierte Ausgabe ersetzt. Das ist es, was die CLI skriptbar macht.

Mehrere Befehle geben ein Array an der Wurzel zurück

log, lock list und repos erzeugen direkt ein JSON-Array, ohne umschließendes Objekt. Es gibt also weder einen Schlüssel commits, noch locks, noch repositories: In jq muss man .[] schreiben, nicht .commits[]. Ein Ausdruck, der auf einen nicht existierenden Schlüssel zielt, erzeugt gar nichts, ohne Fehlermeldung.

Beispiel: `uversion status --json`

{
  "files": [
    {
      "path": "Content/Maps/MainLevel.umap",
      "status": "locked",
      "locked_by": "alice",
      "is_owned": true,
      "version": 12
    },
    {
      "path": "Content/Textures/NewTexture.png",
      "status": "new",
      "locked_by": null,
      "is_owned": false,
      "version": 0
    }
  ],
  "summary": {
    "modified": 1,
    "new": 1,
    "deleted": 0,
    "locked_by_others": 0
  }
}

Die möglichen Werte von status:

Wert	Bedeutung
`modified`	Die Datei ist auf der Festplatte beschreibbar, ohne gesetzte Sperre
`locked`	Von Ihnen reserviert
`locked_other`	Von jemand anderem reserviert, genannt in `locked_by`
`new`	Lokal vorhanden, dem Server unbekannt
`deleted`	Auf dem Server vorhanden, lokal abwesend
`tracked`	Getrackt und unversehrt. Erscheint nur, wenn Sie nach Pfad gefiltert haben

Beachten Sie, dass summary.modified modified und locked addiert, da beide eine Datei bezeichnen, an der Sie arbeiten.

Beispiel: `uversion log --json -n 1`

[
  {
    "commit_hash": "7f3a9b1c2d...",
    "message": "Fixed lighting in main level",
    "author": "alice",
    "created_at": "2026-05-15T08:30:00Z",
    "files": [
      {
        "path": "Content/Maps/MainLevel.umap",
        "revision_number": 12,
        "file_size": 84934656,
        "is_delete": false
      }
    ]
  }
]

Beispiel: `uversion lock list --json`

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "file_id": 12345,
    "file_path": "Content/Maps/MainLevel.umap",
    "user_id": 12,
    "username": "alice",
    "acquired_at": "2026-05-15T08:42:11Z",
    "expires_at": "2126-05-15T08:42:11Z"
  }
]

Das Ablaufdatum 2126 ist kein Tippfehler: Die Spalte darf in der Datenbank nicht leer bleiben, also schreibt der Server einen um hundert Jahre nach hinten geschobenen Wert. Sperren laufen nicht ab. Zeigen Sie dieses Feld keinem Benutzer an und bauen Sie nichts darauf auf.

Fehlerbehandlung

Bei einem Fehlschlag schreibt die CLI Error: <message> auf die Standardfehlerausgabe und endet mit dem Code 1. Fehler werden niemals als JSON auf der Standardausgabe ausgegeben: Mit --json ist nur das Ergebnis eines Erfolgs strukturiert. Testen Sie in einem Skript den Exit-Code, nicht den Inhalt der Ausgabe.

Gängige Muster

Onboarding eines neuen Teammitglieds

uversion login https://uversion.mygamestudio.com -u newdev
uversion repos                                  # confirme l'accès
uversion clone hero-rpg ~/Projects/HeroRPG     # download initial

Täglicher Arbeitsablauf (artist / programmer)

# Début de journée
uversion sync

# Avant d'éditer
uversion checkout Content/Maps/MainLevel.umap

# ... édition dans Unreal Editor ou Rider ...

# Commit en fin de journée
uversion checkin --all -m "Updated main level + hero animations"

Audit-Skript: Wer hat was reserviert?

lock list --json gibt ein Array an der Wurzel zurück. Man iteriert also mit .[], und die Felder sind username, file_path und acquired_at:

uversion lock list --json | jq -r '.[] | "\(.username)\t\(.file_path)\t\(.acquired_at)"'

Die von einer bestimmten Person reservierten Dateien:

uversion lock list --json | jq -r '.[] | select(.username == "bob") | .file_path'

Die Commit-Hashes extrahieren

Auch hier liegt das Array an der Wurzel, und das Feld heißt commit_hash:

uversion log --json -n 50 | jq -r '.[].commit_hash'

Die Commits einer Person, mit ihrer Nachricht:

uversion log --json -n 200 \
  | jq -r '.[] | select(.author == "alice") | "\(.commit_hash[0:8])  \(.message)"'

Ein Asset in einer vergangenen Revision abrufen, ohne den Workspace anzurühren

uversion content erwartet eine Revisionsnummer, keinen Commit-Hash. Finden Sie sie im Verlauf der Datei, wo sie in Klammern angezeigt wird:

$ uversion log --path Content/Characters/Hero.uasset -n 10
commit 6e2b8a0...
Author: bob
Date:   2026-05-14 17:22:00 UTC

    Hero pose pass

    Content/Characters/Hero.uasset (rev 8)

$ uversion content Content/Characters/Hero.uasset --revision 8 --output ~/backup/Hero-v8.uasset

Oder in einem Zug, für die neueste Revision einer Datei:

REV=$(uversion log --json --path Content/Characters/Hero.uasset -n 1 \
  | jq -r '.[0].files[] | select(.path == "Content/Characters/Hero.uasset") | .revision_number')
uversion content Content/Characters/Hero.uasset --revision "$REV" --output ./Hero.uasset

Nächtlicher Build in Continuous Integration

Das Passwort läuft über UVERSION_PASSWORD, niemals über -p: Die Befehlszeile eines Prozesses ist für die anderen Konten der Maschine lesbar.

export UVERSION_PASSWORD="$SECRET_FROM_VAULT"
uversion login "$UV_SERVER" -u ci-nightly
unset UVERSION_PASSWORD

uversion clone hero-rpg ./project
cd project
uversion sync --json > sync.log

# Réserver un fichier pour la durée du cook, et signaler qu'il sert toujours
uversion checkout Content/Cooking/Distribution.uasset
( while pgrep RunUAT; do uversion lock heartbeat; sleep 300; done ) &

# ... build et cook ...

uversion lock release Content/Cooking/Distribution.uasset

Umgebungsvariablen & Exit-Codes

Umgebungsvariablen

Variable	Beschreibung
`UVERSION_PASSWORD`	Von `uversion login` verwendetes Passwort, wenn die Option `-p` fehlt. Das ist die empfohlene Art, eine Anmeldung zu automatisieren: Anders als ein Befehlszeilenargument ist eine Umgebungsvariable den anderen Konten der Maschine nicht ausgesetzt. Ist sie leer oder abwesend, fragt die CLI das Passwort interaktiv ab.
`RUST_LOG`	Ausführlichkeit der Protokolle, geschrieben auf die Standardfehlerausgabe. Zum Beispiel `RUST_LOG=debug`. Standardstufe: `warn`.

Keine UV_*-Variable wird gelesen. Der Server und das Konto stammen aus .uversion/config.toml, wenn Sie sich in einem Workspace befinden, und andernfalls aus der geteilten Konfiguration (unter Windows %APPDATA%/uversion/uVersion/config/config.toml). Das Sitzungstoken stammt aus dem Passwortmanager des Systems. Siehe Welches Konto handelt?.

Exit-Codes

Code	Bedeutung
`0`	Erfolg. Es ist auch der von `--help` und `--version` zurückgegebene Code, die keine Fehler sind.
`1`	Jeder Anwendungsfehler: Authentifizierung, Berechtigung, Netzwerk, Server, Festplattenschreiben, außerhalb des Workspace, Konflikt, Validierung. Die CLI unterscheidet die Ursachen nicht am Exit-Code; die Details stehen auf der Standardfehlerausgabe.
`2`	Fehler beim Parsen der Argumente: unbekannte Option, fehlender Wert, ungültiger Unterbefehl.

Beispiel in einem Shell-Skript:

if ! uversion checkin --all -m "Nightly"; then
  echo "Checkin failed, see stderr"
  exit 1
fi

Installation

Spickzettel: alle Befehle

Authentifizierung

uversion login

uversion logout

Welches Konto handelt? Das des Workspace, nicht das zuletzt angemeldete

Repositories

uversion repos

uversion clone

Dateien

uversion status

uversion checkout

uversion checkin

uversion revert

Umfangreiche Pfadlisten: --paths-file

uversion sync

uversion content

Verlauf

uversion log

Sperren

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Beispiel: uversion status --json

Beispiel: uversion log --json -n 1

Beispiel: uversion lock list --json

Fehlerbehandlung

Gängige Muster

Onboarding eines neuen Teammitglieds

Täglicher Arbeitsablauf (artist / programmer)

Audit-Skript: Wer hat was reserviert?

Die Commit-Hashes extrahieren

Ein Asset in einer vergangenen Revision abrufen, ohne den Workspace anzurühren

Nächtlicher Build in Continuous Integration

Umgebungsvariablen & Exit-Codes

Umgebungsvariablen

Exit-Codes

`uversion login`

`uversion logout`

`uversion repos`

`uversion clone`

`uversion status`

`uversion checkout`

`uversion checkin`

`uversion revert`

Umfangreiche Pfadlisten: `--paths-file`

`uversion sync`

`uversion content`

`uversion log`

`uversion lock list`

`uversion lock release`

`uversion lock heartbeat`

`uversion info`

Beispiel: `uversion status --json`

Beispiel: `uversion log --json -n 1`

Beispiel: `uversion lock list --json`