Wiki

CLI uversion

Riferimento completo della CLI di uVersion: tutti i comandi, i flag, gli esempi, JSON output, i codici di uscita.

Il binario uversion copre le stesse operazioni di versionamento del client desktop, in più con un output --json utilizzabile da un programma, per l'automazione: integrazione continua, script di onboarding, strumenti fatti in casa. Questa pagina si rivolge agli sviluppatori e agli amministratori di studio.

Installazione

Su Windows, il binario uversion.exe è incluso nell'installer del client desktop e aggiunto automaticamente al PATH utente (%LOCALAPPDATA%\uVersion). La voce del PATH viene deduplicata a ogni aggiornamento e rimossa alla disinstallazione. Aprite un nuovo terminale e digitate:

uversion --help

Su macOS è automatico: al primo avvio, il client desktop crea un collegamento al binario incorporato in ~/.local/bin/uversion e si assicura che quella cartella sia nel PATH (tramite ~/.zprofile). Avviate l'applicazione una volta, aprite un nuovo terminale, e il comando uversion è disponibile. Per farlo a mano verso un'altra posizione del PATH:

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

Su Linux è automatico anche qui, esattamente come su macOS. Il client desktop è distribuito come AppImage, e questa AppImage contiene il binario uversion. Al primo avvio, l'applicazione lo colloca in ~/.local/bin/uversion e si assicura che quella cartella sia nel PATH. Avviate l'applicazione una volta, aprite un nuovo terminale, e il comando è disponibile:

uversion --help

Non dovete compilare nulla. Su Linux, il client desktop viene distribuito unicamente come AppImage, ed è essa a portare la CLI. Per collocare il binario altrove nel PATH, copiatelo da ~/.local/bin:

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

Per verificare la versione installata:

$ uversion --version

Cheatsheet: tutti i comandi

L'insieme dei comandi disponibili, nell'ordine in cui li si incontra tipicamente:

Comando	Cosa fa
`uversion login <url> -u <user>`	Autenticarsi su un server
`uversion logout`	Cancellare le credenziali memorizzate
`uversion repos`	Elencare i repository accessibili
`uversion clone <repo> [path]`	Clonare un repository
`uversion info`	Mostrare lo stato del workspace + l'utente corrente
`uversion status [paths...]`	Vedere i file modificati / nuovi / eliminati / bloccati
`uversion checkout <paths...>`	Riservare file per la modifica (mette un lock)
`uversion checkin <paths...> -m "..."`	Caricare e confermare le modifiche
`uversion revert <paths...>`	Annullare le modifiche locali e rilasciare i lock
`uversion sync`	Recuperare le modifiche dal server (intero repository)
`uversion content <path> --revision <n>`	Scaricare una versione precisa di un file
`uversion log`	Cronologia dei commit
`uversion lock list`	Vedere tutti i lock del repository
`uversion lock release <paths...>`	Rilasciare un lock senza toccare il file
`uversion lock heartbeat`	Segnalare che i vostri lock sono ancora in uso (per il monitoraggio)
`uversion trust <url>`	Memorizzare l'impronta del certificato autofirmato di un server (interattivo; `--yes` per lo scripting)
`uversion mistrust <url>`	Dimenticare l'impronta memorizzata di un server
`uversion trusted`	Elencare i server la cui impronta è memorizzata

Tutti i comandi tranne uversion content accettano --json, che sostituisce la visualizzazione leggibile con un output utilizzabile da un programma (vedi JSON output). Tutti accettano --help per il dettaglio delle opzioni.

checkout, checkin e revert accettano anche --paths-file <fichier>, indispensabile non appena si lavora alla scala di un progetto Unreal. Vedi Liste di percorsi voluminose.

Autenticazione

`uversion login`

Si autentica presso un server uVersion. Il server consegna un token di sessione (un JWT, per JSON Web Token), che la CLI ripone nel gestore delle password del sistema: Gestione credenziali su Windows, Portachiavi su macOS, libsecret su Linux. Questo token è condiviso con il client desktop, il plugin di Unreal e il plugin di Rider: connettersi da un lato connette gli altri, e disconnettersi li disconnette tutti.

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

Opzione	Descrizione
`-u, --username`	Nome utente
`-p, --password`	Sconsigliato. Vedi il riquadro qui sotto. Se l'opzione è omessa, la CLI legge la variabile d'ambiente `UVERSION_PASSWORD`, e in mancanza chiede la password in modo interattivo, senza eco a schermo.

Per fare lo scripting di una connessione, usate UVERSION_PASSWORD, mai -p

Su un sistema multiutente, la riga di comando di ogni processo è leggibile dagli altri account della macchina: ps su Linux e macOS, Gestione attività o wmic su Windows. Una password passata come argomento vi appare in chiaro, anche se proviene da una variabile, poiché la shell la sostituisce con il suo valore prima di lanciare il programma. Finisce anche nella cronologia della shell e spesso nei log della catena di integrazione continua.

La CLI legge UVERSION_PASSWORD proprio per evitarlo, e mostra un avviso sullo standard error quando si usa -p.

Esempi:

$ 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)

Alla prima connessione a un server che presenta un certificato autofirmato, la CLI mostra l'impronta del certificato e vi chiede di confermarla, poi la memorizza. È il principio della fiducia al primo contatto, lo stesso di SSH: si accetta un'identità una volta, e ogni successiva presentazione di un'identità diversa viene segnalata. Se l'impronta cambia, la CLI rifiuta la connessione e vi avvisa: è o un rinnovo legittimo del certificato, o un'intercettazione del vostro traffico da parte di un terzo. La manovra deliberata è allora uversion mistrust <url>, seguita da una nuova connessione.

`uversion logout`

Cancella il token dal gestore delle password del sistema e invalida sul server tutte le sessioni di questo account. Poiché il token è condiviso, questo disconnette anche il client desktop, il plugin di Unreal e il plugin di Rider, su tutte le vostre macchine.

$ uversion logout
Logged out (alice)

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

Quale account agisce? Quello del workspace, non l'ultimo connesso

È il punto che sorprende di più, ed è meglio conoscerlo prima di fare lo scripting di qualsiasi cosa: l'identità utilizzata non è quella dell'ultima connessione, è quella del workspace in cui vi trovate.

Un workspace è una cartella clonata, riconoscibile dalla sua sottocartella .uversion. Il file .uversion/config.toml vi registra il server e l'account proprietario:

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

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

Non appena siete in un workspace, server_url e owner fanno testo: status, checkout, checkin, revert, sync, log, content, lock e info si autenticano come owner, verso server_url.

Solo login, logout, repos e clone usano la configurazione condivisa tra tutti i workspace (su Windows %APPDATA%/uversion/uVersion/config/config.toml), che segue l'account attivo del client desktop.

Perché. Una stessa postazione serve spesso più account, per esempio un freelance che lavora per due studi. Senza questa regola, tutti i workspace agirebbero sotto l'account attivo del momento: una cartella clonata da alice ma usata mentre bob è attivo metterebbe i suoi lock a nome di bob, vedrebbe i propri file come «bloccati da qualcun altro», e si vedrebbe rifiutare gli invii.

Per cambiare l'identità di un workspace, modificate il campo owner in .uversion/config.toml, e assicuratevi che quell'account si sia connesso almeno una volta su questa macchina (uversion login), affinché il suo token sia presente. Verificate poi con uversion info, che mostra l'account realmente utilizzato.

Limite noto: uno stesso nome utente su due server

Il token è riposto sotto il solo nome utente, senza il server. Se lo stesso nome esiste su due server uVersion diversi, entrambi condividono una sola e medesima voce: connettersi al secondo sostituisce il token del primo. Usate nomi distinti, oppure impiegate un solo server alla volta da una stessa macchina.

Repository

`uversion repos`

Elenca i repository a cui l'account ha accesso. Questo comando usa la configurazione condivisa, non quella di un workspace: risponde quindi per l'account della vostra ultima connessione.

$ 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`

Recupera un repository in locale. Se il percorso è omesso, viene creata una cartella con il nome del repository nella directory corrente. Il clone crea anche la sottocartella .uversion, che rende la cartella un workspace e registra il server e l'account proprietario.

Il trasferimento applica la deduplicazione: il contenuto viene suddiviso in blocchi, e un blocco già presente viene memorizzato una sola volta, anche se compare in più file. È per questo che lo spazio occupato su disco è spesso nettamente inferiore al volume scaricato.

uversion clone <repo_name_or_id> [local_path]

Esempi:

$ 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

File

`uversion status`

Mostra lo stato dei file del workspace corrente: modificati, nuovi (untracked), eliminati, bloccati da altri.

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

Esempi:

$ 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`

Mette un lock esclusivo sui file indicati e li rende modificabili su disco. I file tracciati sono in sola lettura finché non sono riservati: è ciò che evita che due persone modifichino lo stesso asset binario in parallelo.

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

Opzione	Descrizione
`--paths-file`	Leggere percorsi aggiuntivi da un file, uno per riga. Vedi Liste di percorsi voluminose.
`--force`	Prende il lock anche se è detenuto da qualcun altro. Riservato agli account che possiedono la capacità `force_unlock`, cioè i ruoli `admin` e `lead`. Vedi qui sotto.
`--add`	Autorizza la riserva di percorsi ancora assenti in locale, per file nuovi.

Cosa fa davvero --force

L'opzione prende il lock di qualcun altro. È protetta dalla capacità force_unlock, detenuta dai ruoli admin e lead. Un account che non ce l'ha riceve un rifiuto esplicito, con il rimedio da seguire: chiederlo a un amministratore, o usare il pulsante «Richiedi il rilascio» del client desktop, che avvisa la persona interessata.

Quando una sottrazione ha effettivamente avuto luogo, viene registrata nel log di audit, con i percorsi interessati e il nome delle persone a cui i lock sono stati presi. Nulla viene scritto se l'opzione era presente ma nessun lock altrui ha cambiato mano: negli script, il flag è spesso sistematico, e un log pieno di eventi senza oggetto è un log che nessuno rilegge.

Esempi:

$ 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`

Carica i file modificati e li conferma sul server in una sola transazione: o passa tutto, o niente. I lock vengono rilasciati automaticamente in caso di successo.

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

Opzione	Descrizione
`-m, --message`	Messaggio di commit. Obbligatorio.
`-a, --all`	Includere tutti i file modificati del workspace, non solo quelli passati come argomento.
`--paths-file`	Leggere percorsi aggiuntivi da un file, uno per riga. Vedi Liste di percorsi voluminose.

Esempi:

$ 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`

Abbandona le modifiche locali di uno o più file, ripristina la versione del server e rilascia i lock corrispondenti.

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

Esempi:

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

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

Liste di percorsi voluminose: `--paths-file`

checkout, checkin e revert accettano --paths-file <fichier>: un file di testo contenente un percorso per riga. I percorsi così letti si aggiungono a quelli passati come argomento, non li sostituiscono.

A cosa serve. Su un progetto Unreal, un'operazione riguarda comunemente diverse migliaia di file. Passarli tutti come argomenti si scontra con un limite del sistema: su Windows, una riga di comando non può superare i 32.767 caratteri, il che rappresenta circa 500 percorsi di asset. Oltre, il comando fallisce ancor prima di avviarsi, con un messaggio di errore del sistema che non dice nulla del problema reale. --paths-file elimina questo limite: il file può contenerne quanti ne servono.

Riservare tutti i file modificati di una cartella, qualunque sia il numero:

$ 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

Poi inviare esattamente lo stesso lotto:

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

Su 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

È anche il meccanismo che il plugin di Rider impiega per trasmettere un insieme di modifiche voluminoso.

`uversion sync`

Scarica le ultime modifiche dal server e le applica al workspace locale.

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

Flag	Descrizione
`-f, --force`	Sync completo: riscarica tutti i file, non solo il delta dall'ultimo sync. Utile in caso di workspace corrotto.

Esempi:

$ 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`

Scarica una versione precisa di un file senza toccare il workspace locale. Utile per confrontare, archiviare, o recuperare uno stato passato senza fare un revert.

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

--revision si aspetta un numero intero, non un'impronta di commit

È il numero di revisione del file: un contatore che vale 1 alla sua prima versione, 2 alla seconda, e così via. Passare un'impronta di commit come 6e2b8a0 fa fallire il comando già all'analisi degli argomenti.

Il numero si legge in uversion log --path <fichier>, dove ogni riga di file lo mostra tra parentesi. Omettere --revision scarica l'ultima versione.

Esempi:

$ 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

Cronologia

`uversion log`

Cronologia dei commit del repository corrente, opzionalmente filtrata per file.

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

Flag	Descrizione
`-n, --limit`	Numero di voci da mostrare (predefinito: 20)
`-p, --path`	Filtra per percorso di file

Esempi:

$ 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

Una riga contrassegnata come deleted è una revisione di eliminazione: porta un numero come le altre, ma non ha contenuto da scaricare.

Lock

Un lock non scade mai

Resta finché non viene esplicitamente rilasciato: tramite uversion checkin, tramite uversion revert, tramite uversion lock release, o tramite uno sblocco forzato di un amministratore. Non esiste alcuna scadenza automatica, né dopo un'ora, né dopo un mese. Un file riservato e dimenticato lo resta finché qualcuno non interviene.

Di conseguenza, uversion lock heartbeat non prolunga nulla. Questo comando dice soltanto «questi lock mi servono ancora», affinché gli amministratori distinguano un lock attivo da uno abbandonato.

`uversion lock list`

Mostra tutti i lock del repository corrente.

uversion lock list [--json]

Esempi:

$ 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

Se non c'è nulla da mostrare, il comando scrive No active locks.

`uversion lock release`

Rilascia uno o più lock senza toccare il contenuto locale del file. Da usare per «restituire» un asset che non si è modificato: riservato per errore, o lavoro abbandonato senza invio.

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

Esempi:

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

Questo comando rilascia solo i vostri lock. Per rimuovere quello di qualcun altro, bisogna passare per l'amministrazione, o per uversion checkout --force se siete admin o lead.

`uversion lock heartbeat`

Segnala che i lock detenuti dall'account corrente sono ancora in uso. Questo non li prolunga: nulla scade. È un segnale di monitoraggio, affinché un amministratore che ispeziona la lista dei lock veda quali sono ancora attivi. Inutile nel lavoro quotidiano; utile per un'elaborazione automatizzata che tiene un file riservato per ore.

$ uversion lock heartbeat
3 lock(s) extended

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

Esempio in integrazione continua:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Info

`uversion info`

Mostra l'account utilizzato e lo stato del workspace corrente. È il comando da lanciare per primo quando qualcosa si comporta in modo inatteso: mostra sotto quale identità la CLI agisce realmente, che è quella del proprietario del workspace e non necessariamente quella della vostra ultima connessione (vedi Quale account agisce?).

$ 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

Fuori da un workspace, o senza una sessione valida:

$ uversion info
User: not logged in

Workspace: not in a uVersion workspace

Il comando non conta i file e non mostra un riepilogo delle modifiche: è il ruolo di uversion status.

JSON output

Tutti i comandi tranne content accettano --json, che sostituisce la visualizzazione leggibile con un output strutturato. È ciò che rende la CLI scriptabile.

Diversi comandi restituiscono un array alla radice

log, lock list e repos producono direttamente un array JSON, senza oggetto contenitore. Non c'è quindi né una chiave commits, né una chiave locks, né una chiave repositories: è .[] che bisogna scrivere in jq, non .commits[]. Un'espressione che punta a una chiave inesistente non produce nulla, senza messaggio di errore.

Esempio: `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
  }
}

I valori possibili di status:

Valore	Significato
`modified`	Il file è modificabile su disco, senza lock messo
`locked`	Riservato da voi
`locked_other`	Riservato da qualcun altro, nominato in `locked_by`
`new`	Presente in locale, sconosciuto al server
`deleted`	Presente sul server, assente in locale
`tracked`	Tracciato e intatto. Appare solo se avete filtrato per percorso

Notate che summary.modified somma modified e locked, poiché entrambi designano un file su cui state lavorando.

Esempio: `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
      }
    ]
  }
]

Esempio: `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"
  }
]

La scadenza al 2126 non è un refuso: la colonna non può restare vuota nel database, quindi il server vi scrive un valore spinto avanti di cent'anni. I lock non scadono. Non mostrate questo campo a un utente e non costruite nulla su di esso.

Gestione degli errori

In caso di fallimento, la CLI scrive Error: <message> sullo standard error e termina con il codice 1. Gli errori non vengono mai emessi in JSON sullo standard output: con --json, solo il risultato di un successo è strutturato. In uno script, testate il codice di uscita, non il contenuto dell'output.

Pattern comuni

Onboarding di un nuovo membro del team

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

Flusso di lavoro quotidiano (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"

Script di audit: chi ha riservato cosa?

lock list --json restituisce un array alla radice. Si itera quindi con .[], e i campi sono username, file_path e acquired_at:

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

I file riservati da una determinata persona:

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

Estrarre le impronte di commit

Anche qui l'array è alla radice, e il campo si chiama commit_hash:

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

I commit di una persona, con il loro messaggio:

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

Recuperare un asset a una revisione passata, senza toccare il workspace

uversion content si aspetta un numero di revisione, non un'impronta di commit. Individuatelo nella cronologia del file, dove viene mostrato tra parentesi:

$ 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

Oppure in una volta sola, per l'ultima revisione di un file:

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

Build notturna in integrazione continua

La password passa per UVERSION_PASSWORD, mai per -p: la riga di comando di un processo è leggibile dagli altri account della macchina.

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

Variabili d'ambiente e codici di uscita

Variabili d'ambiente

Variabile	Descrizione
`UVERSION_PASSWORD`	Password usata da `uversion login` quando l'opzione `-p` è assente. È il modo raccomandato per automatizzare una connessione: a differenza di un argomento della riga di comando, una variabile d'ambiente non è esposta agli altri account della macchina. Se è vuota o assente, la CLI chiede la password in modo interattivo.
`RUST_LOG`	Verbosità dei log, scritti sullo standard error. Per esempio `RUST_LOG=debug`. Livello predefinito: `warn`.

Nessuna variabile UV_* viene letta. Il server e l'account provengono da .uversion/config.toml quando siete in un workspace, e altrimenti dalla configurazione condivisa (su Windows %APPDATA%/uversion/uVersion/config/config.toml). Il token di sessione proviene dal gestore delle password del sistema. Vedi Quale account agisce?.

Codici di uscita

Codice	Significato
`0`	Successo. È anche il codice restituito da `--help` e da `--version`, che non sono errori.
`1`	Qualsiasi errore applicativo: autenticazione, permesso, rete, server, scrittura su disco, fuori dal workspace, conflitto, validazione. La CLI non distingue le cause tramite il codice di uscita; il dettaglio è sullo standard error.
`2`	Errore di analisi degli argomenti: opzione sconosciuta, valore mancante, sottocomando non valido.

Esempio in uno script shell:

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

Installazione

Cheatsheet: tutti i comandi

Autenticazione

uversion login

uversion logout

Quale account agisce? Quello del workspace, non l'ultimo connesso

Repository

uversion repos

uversion clone

File

uversion status

uversion checkout

uversion checkin

uversion revert

Liste di percorsi voluminose: --paths-file

uversion sync

uversion content

Cronologia

uversion log

Lock

uversion lock list

uversion lock release

uversion lock heartbeat

Info

uversion info

JSON output

Esempio: uversion status --json

Esempio: uversion log --json -n 1

Esempio: uversion lock list --json

Gestione degli errori

Pattern comuni

Onboarding di un nuovo membro del team

Flusso di lavoro quotidiano (artist / programmer)

Script di audit: chi ha riservato cosa?

Estrarre le impronte di commit

Recuperare un asset a una revisione passata, senza toccare il workspace

Build notturna in integrazione continua

Variabili d'ambiente e codici di uscita

Variabili d'ambiente

Codici di uscita

`uversion login`

`uversion logout`

`uversion repos`

`uversion clone`

`uversion status`

`uversion checkout`

`uversion checkin`

`uversion revert`

Liste di percorsi voluminose: `--paths-file`

`uversion sync`

`uversion content`

`uversion log`

`uversion lock list`

`uversion lock release`

`uversion lock heartbeat`

`uversion info`

Esempio: `uversion status --json`

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

Esempio: `uversion lock list --json`