Wiki

CLI uversion

uVersion CLI 完整参考：所有命令、标志、示例、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`	显示工作区状态和当前用户
`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、Linux 上的 libsecret）中，并与桌面客户端和编辑器插件共享。

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`

显示当前工作区中文件的状态：已修改、新增（未跟踪）、已删除、被他人锁定。

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` 权限（默认为管理员）。已审计。
`--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`	包含工作区中所有已修改的文件，而不仅是作为参数传入的文件

示例：

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

从服务器下载最新更改并应用到本地工作区。

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

Flag	Description
`-f, --force`	完整同步：重新下载所有文件，而不仅是自上次同步以来的增量。在工作区损坏时很有用。

示例：

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

在不触碰本地工作区的情况下，下载文件的特定版本（按修订号）。用于比较、归档或获取历史状态而无需执行 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`

显示当前工作区、已认证用户和同步状态的信息。

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

获取过去某个修订版的资产（不触碰工作区）

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、工作区之外、冲突、验证等）。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