Wiki

CLI uversion

Полный справочник по CLI uVersion: все команды, флаги, примеры, JSON output, коды выхода.

Бинарный файл uversion охватывает все операции VCS, доступные в десктоп-клиенте, а также предоставляет машиночитаемый вывод --json для автоматизации (CI/CD, скрипты онбординга, интеграция со сторонними инструментами). Всё содержимое этой страницы предназначено для разработчиков и администраторов студии.

Установка

В Windows бинарный файл uversion.exe входит в установщик десктоп-клиента и автоматически добавляется в PATH пользователя (%LOCALAPPDATA%\uVersion). Запись в PATH дедуплицируется при каждом обновлении и удаляется при деинсталляции. Откройте новый терминал и введите:

uversion --help

В macOS это происходит автоматически: при первом запуске десктоп-клиент создаёт ссылку на встроенный бинарный файл в ~/.local/bin/uversion и следит за тем, чтобы эта папка была в PATH (через ~/.zprofile). Запустите приложение один раз, откройте новый терминал, и команда uversion станет доступна. Чтобы сделать это вручную в другое место PATH:

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

В Linux CLI пока не входит в пакеты .deb / .AppImage. Соберите его из исходников, если он вам нужен:

git clone https://github.com/jeremweb/uversion
cargo build -p uversion-cli --release
sudo cp target/release/uversion /usr/local/bin/

Чтобы проверить установленную версию:

$ uversion --version

Шпаргалка: все команды

Полный набор доступных команд в порядке, в котором с ними обычно сталкиваются:

Команда	Что делает
`uversion login <url> -u <user>`	Аутентификация на сервере
`uversion logout`	Очистить сохранённые учётные данные
`uversion repos`	Показать доступные репозитории
`uversion clone <repo> [path]`	Клонировать репозиторий
`uversion info`	Показать состояние workspace + текущего пользователя
`uversion status [paths...]`	Просмотреть изменённые / новые / удалённые / заблокированные файлы
`uversion checkout <paths...>`	Заблокировать файлы для редактирования
`uversion checkin <paths...> -m "..."`	Загрузить и закоммитить изменения
`uversion revert <paths...>`	Отменить локальные изменения, снять блокировки
`uversion sync`	Получить изменения с сервера (весь репозиторий)
`uversion content <path> --revision <rev>`	Скачать конкретную версию файла
`uversion log`	История коммитов
`uversion lock list`	Показать все активные блокировки репозитория
`uversion lock release <paths...>`	Снять блокировку, не трогая файл
`uversion lock heartbeat`	Продлить срок действия всех удерживаемых блокировок (длительные задания CI)
`uversion trust <url>`	Закрепить самоподписанный отпечаток TLS сервера (TOFU, интерактивно; `--yes` для скриптов)
`uversion mistrust <url>`	Удалить закреплённый отпечаток сервера
`uversion trusted`	Показать серверы с закреплённым отпечатком

Все команды (кроме uversion content) принимают --json для получения машиночитаемого вывода (см. JSON output). Все команды также принимают --help для подробностей о флагах.

Аутентификация

`uversion login`

Выполняет аутентификацию на сервере uVersion. Возвращённый JWT сохраняется в системном keyring (Windows Credential Manager, macOS Keychain, libsecret в Linux) и используется совместно с десктоп-клиентом и плагинами редактора.

uversion login <server_url> -u <username> [-p <password>]

Flag	Description
`-u, --username`	Имя пользователя
`-p, --password`	Пароль. Если опущен, появляется скрытый запрос (без эха)

Примеры:

$ uversion login https://uversion.mygamestudio.com -u alice
Password: ********
✓ Authenticated as alice (role: artist)

$ uversion login http://192.168.1.100:3000 -u bob -p $UV_PASSWORD
✓ Authenticated as bob (role: programmer)

$ uversion login https://uversion.mygamestudio.com -u ci-nightly -p "$UV_PASSWORD"
✓ Authenticated as ci-nightly (role: programmer)

`uversion logout`

Удаляет токен из системного keyring. Следующая команда, требующая аутентификации, снова запросит пароль.

$ uversion logout
✓ Credentials cleared

Репозитории

`uversion repos`

Показывает репозитории, к которым имеет доступ текущий пользователь.

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

Клонирует репозиторий локально. Если local_path опущен, в текущем рабочем каталоге создаётся папка с именем репозитория.

uversion clone <repo_name_or_id> [local_path]

Примеры:

$ 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

Файлы

`uversion status`

Показывает состояние файлов текущего workspace: изменённые, новые (неотслеживаемые), удалённые, заблокированные другими.

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

Примеры:

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

Получает эксклюзивную блокировку на целевые файлы и делает их доступными для записи на диске.

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

Flag	Description
`--force`	Принудительный checkout, даже если файл заблокирован другим пользователем. Требует возможности `force_unlock` (по умолчанию admin). Аудируется.
`--add`	Разрешает checkout путей, ещё отсутствующих локально (новые файлы)

Примеры:

$ 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

$ uversion checkout Content/Maps/MainLevel.umap   # déjà locked par bob
✗ Locked by bob since 2026-05-15T08:42:11Z. Use --force if you have permission, or request release.

$ uversion checkout --force Content/Maps/MainLevel.umap   # admin force-steal
⚠ Forced lock takeover (was bob)
✓ Lock acquired: Content/Maps/MainLevel.umap

`uversion checkin`

Загружает изменённые файлы и коммитит их на сервер в одной атомарной транзакции. После успеха блокировки снимаются автоматически.

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

Flag	Description
`-m, --message`	Сообщение коммита (обязательно)
`-a, --all`	Включить все изменённые файлы в workspace, а не только переданные в аргументах

Примеры:

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

Отменяет локальные изменения одного или нескольких файлов, восстанавливает серверную версию, снимает соответствующие блокировки.

uversion revert <paths...>

Примеры:

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

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

`uversion sync`

Скачивает последние изменения с сервера и применяет их к локальному workspace.

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

Flag	Description
`-f, --force`	Полная синхронизация: повторно скачивает все файлы, а не только дельту с момента последней синхронизации. Полезно при повреждённом workspace.

Примеры:

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

Скачивает конкретную версию файла (по номеру ревизии), не трогая локальный workspace. Полезно для сравнения, архивирования или получения исторического состояния без выполнения revert.

uversion content <path> [-r <revision>] [-o <file>]

Примеры:

$ uversion content Content/Maps/MainLevel.umap --revision 12 --output ./snapshot.umap
✓ Downloaded MainLevel.umap @ rev 12 → ./snapshot.umap (84 MB)

$ uversion content Content/Characters/Hero.uasset --revision 12 --output ./hero-v12.uasset

История

`uversion log`

История коммитов текущего репозитория, при желании отфильтрованная по файлу.

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

Flag	Description
`-n, --limit`	Количество отображаемых записей (по умолчанию: 20)
`-p, --path`	Фильтр по пути к файлу

Примеры:

$ uversion log
commit 7f3a9b1c2d... (HEAD)
Author: alice
Date:   2026-05-15T08:30:00Z

    Fixed lighting in main level

    Content/Maps/MainLevel.umap (rev 12)

commit 6e2b8a0...
Author: bob
Date:   2026-05-14T17:22:00Z

    Hero pose pass

    Content/Characters/Hero.uasset (rev 8)

$ uversion log -n 5                                      # 5 derniers commits
$ uversion log --path Content/Maps/MainLevel.umap        # historique d'un fichier
$ uversion log --json -n 50 | jq '.commits[].hash'       # extract hashes en CI

Блокировки

`uversion lock list`

Показывает все активные блокировки в текущем репозитории.

uversion lock list [--json]

Примеры:

$ 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

3 locks active

`uversion lock release`

Вручную снимает одну или несколько блокировок, не трогая локальное содержимое файла. Используйте, когда хотите «вернуть» ассет, не внося изменений (обычно вы сделали checkout по ошибке или бросаете начатую работу, не отправляя её).

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

Примеры:

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

`uversion lock heartbeat`

Продлевает срок действия всех блокировок, удерживаемых текущим пользователем. Для обычного рабочего процесса не требуется; используется заданиями CI, которые удерживают блокировку долгое время, чтобы администраторы видели, что блокировка ещё активна.

uversion lock heartbeat

Типичный пример в CI:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

Информация

`uversion info`

Показывает информацию о текущем workspace, аутентифицированном пользователе и состоянии синхронизации.

$ uversion info
User: alice (lead)

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

Files: 8,432 (5 modified, 2 locked by you, 3 locked by others)

JSON output

Все команды принимают флаг --json для получения машиночитаемого вывода вместо отображения для человека. Незаменимо для написания скриптов CLI в пайплайнах.

Пример: `uversion status --json`

{
  "files": [
    {
      "path": "Content/Maps/MainLevel.umap",
      "status": "modified",
      "lock": { "user": "alice", "acquired_at": "2026-05-15T08:42:11Z" }
    },
    {
      "path": "Content/Textures/NewTexture.png",
      "status": "new",
      "lock": null
    }
  ],
  "summary": {
    "modified": 1,
    "new": 1,
    "deleted": 0,
    "locked_by_others": 0
  }
}

Пример: `uversion log --json -n 1`

{
  "commits": [
    {
      "hash": "7f3a9b1c2d...",
      "author": "alice",
      "date": "2026-05-15T08:30:00Z",
      "message": "Fixed lighting in main level",
      "files": [
        { "path": "Content/Maps/MainLevel.umap", "action": "modified", "revision": 12 }
      ]
    }
  ]
}

Обработка ошибок

В случае сбоя CLI записывает Error: <message> в stderr и завершается с кодом 1. Ошибки не выводятся как JSON в stdout: в режиме --json структурирован только успешный вывод. В своих скриптах проверяйте код выхода (не ноль = сбой).

Типовые сценарии

Онбординг нового участника команды

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

Ежедневный рабочий процесс (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"

Скрипт аудита: кто что заблокировал?

uversion lock list --json | jq -r '.locks[] | "\(.user)\t\(.path)\t\(.acquired_at)"'

Получение ассета на прошлой ревизии (не трогая workspace)

uversion log --path Content/Characters/Hero.uasset -n 10    # repère le commit voulu
uversion content Content/Characters/Hero.uasset --revision 6e2b8a0 --output ~/backup/Hero-v8.uasset

Ночная сборка CI

uversion login "$UV_SERVER" -u ci-nightly -p "$UV_PASSWORD"
uversion clone hero-rpg ./project
cd project
uversion sync --json > sync.log

# Tenir le lock pendant un long cook
uversion checkout Content/Cooking/Distribution.uasset
( while pgrep RunUAT; do uversion lock heartbeat; sleep 300; done ) &

# ... build / cook ...

uversion lock release Content/Cooking/Distribution.uasset

Переменные окружения и коды выхода

Переменные окружения

Variable	Description
`RUST_LOG`	Управляет подробностью логов (пишутся в stderr), напр. `RUST_LOG=debug`. Уровень по умолчанию: `warn`. Это единственная переменная окружения, которую читает CLI.

URL сервера и имя пользователя берутся из config.toml (%APPDATA%/uversion/uVersion/config/), токен из системного keyring: никакая переменная UV_* не читается.

Коды выхода

Код	Значение
`0`	Успех
`1`	Любая ошибка приложения (аутентификация, права, сеть, сервер, IO, вне workspace, конфликт, валидация…). CLI не различает ошибки по коду выхода.
`2`	Ошибка разбора аргументов, `--help` или `--version` (соглашение clap)

Пример использования в bash-скрипте:

uversion checkin --all -m "Nightly"
if [ $? -ne 0 ]; then
  echo "Checkin failed, see logs (stderr)"
  exit 1
fi

Установка

Шпаргалка: все команды

Аутентификация

uversion login

uversion logout

Репозитории

uversion repos

uversion clone

Файлы

uversion status

uversion checkout

uversion checkin

uversion revert

uversion sync

uversion content

История

uversion log

Блокировки

uversion lock list

uversion lock release

uversion lock heartbeat

Информация

uversion info

JSON output

Пример: uversion status --json

Пример: uversion log --json -n 1

Обработка ошибок

Типовые сценарии

Онбординг нового участника команды

Ежедневный рабочий процесс (artist / programmer)

Скрипт аудита: кто что заблокировал?

Получение ассета на прошлой ревизии (не трогая workspace)

Ночная сборка CI

Переменные окружения и коды выхода

Переменные окружения

Коды выхода

`uversion login`

`uversion logout`

`uversion repos`

`uversion clone`

`uversion status`

`uversion checkout`

`uversion checkin`

`uversion revert`

`uversion sync`

`uversion content`

`uversion log`

`uversion lock list`

`uversion lock release`

`uversion lock heartbeat`

`uversion info`

Пример: `uversion status --json`

Пример: `uversion log --json -n 1`