Wiki

CLI uversion

uVersion CLI 전체 레퍼런스: 모든 명령, 플래그, 예제, JSON output, 종료 코드.

uversion 바이너리는 데스크톱 클라이언트와 동일한 버전 관리 작업을 모두 다루며, 여기에 프로그램이 다룰 수 있는 --json 출력을 더해 자동화에 활용할 수 있습니다: 지속적 통합, 온보딩 스크립트, 자체 제작 도구 등. 이 페이지는 개발자와 스튜디오 관리자를 위한 것입니다.

설치

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 에서도 macOS와 정확히 같은 방식으로 자동입니다. 데스크톱 클라이언트는 AppImage로 배포되며, 이 AppImage에는 uversion 바이너리가 포함되어 있습니다. 최초 실행 시 앱이 그것을 ~/.local/bin/uversion 에 배치하고 그 폴더가 PATH에 있도록 보장합니다. 앱을 한 번 실행하고 새 터미널을 열면 명령을 사용할 수 있습니다:

uversion --help

컴파일할 것은 아무것도 없습니다. Linux에서 데스크톱 클라이언트는 AppImage로만 배포되며, 그것이 CLI를 함께 제공합니다. 바이너리를 PATH의 다른 곳에 두려면 ~/.local/bin 에서 복사하세요:

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

설치된 버전을 확인하려면:

$ 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 <n>`	파일의 특정 버전을 다운로드한다
`uversion log`	커밋 히스토리
`uversion lock list`	저장소의 모든 잠금을 본다
`uversion lock release <paths...>`	파일을 건드리지 않고 잠금을 해제한다
`uversion lock heartbeat`	잠금이 아직 사용 중임을 알린다(모니터링용)
`uversion trust <url>`	서버의 자체 서명 인증서 지문을 기억한다(대화식, 스크립트에는 `--yes`)
`uversion mistrust <url>`	서버의 기억된 지문을 잊는다
`uversion trusted`	지문이 기억된 서버를 나열한다

uversion content 를 제외한 모든 명령은 --json 을 받습니다. 이는 읽기 쉬운 표시를 프로그램이 다룰 수 있는 출력으로 바꿉니다(JSON output 참조). 모든 명령은 옵션 세부 정보를 위한 --help 도 받습니다.

checkout, checkin, revert 는 --paths-file <fichier> 도 받습니다. Unreal 프로젝트 규모의 작업에서는 필수적입니다. 대량 경로 목록을 참조하세요.

인증

`uversion login`

uVersion 서버에서 인증합니다. 서버는 세션 토큰(JSON Web Token 인 JWT)을 돌려주고, CLI는 이를 시스템 비밀번호 관리자에 저장합니다: Windows에서는 자격 증명 관리자, macOS에서는 키체인, Linux에서는 libsecret입니다. 이 토큰은 데스크톱 클라이언트, Unreal 플러그인, Rider 플러그인과 공유되어, 한쪽에서 로그인하면 다른 쪽도 로그인되고 로그아웃하면 모두 로그아웃됩니다.

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

옵션	설명
`-u, --username`	사용자 이름
`-p, --password`	권장하지 않음. 아래 상자를 참조하세요. 이 옵션을 생략하면 CLI는 환경 변수 `UVERSION_PASSWORD` 를 읽고, 그것도 없으면 화면에 표시하지 않고 대화식으로 비밀번호를 묻습니다.

로그인을 스크립트화하려면 -p 가 아니라 UVERSION_PASSWORD 를 사용하세요

다중 사용자 시스템에서는 각 프로세스의 명령줄을 머신의 다른 계정이 읽을 수 있습니다: Linux와 macOS에서는 ps, Windows에서는 작업 관리자나 wmic. 인수로 전달된 비밀번호는 거기에 평문으로 나타나며, 변수에서 왔더라도 마찬가지입니다. 셸이 프로그램을 실행하기 전에 변수를 그 값으로 치환하기 때문입니다. 또한 셸 히스토리에도, 종종 지속적 통합 로그에도 남습니다.

CLI는 바로 이를 피하기 위해 UVERSION_PASSWORD 를 읽으며, -p 가 사용되면 표준 오류 출력에 경고를 표시합니다.

예:

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

자체 서명 인증서를 제시하는 서버에 처음 연결할 때, CLI는 인증서 지문을 표시하고 확인을 요청한 뒤 이를 기억합니다. 이것이 SSH와 같은 최초 접속 시 신뢰(Trust On First Use) 원칙입니다: 아이덴티티를 한 번 받아들이면, 이후 다른 아이덴티티가 제시될 때마다 알려줍니다. 지문이 바뀌면 CLI는 연결을 거부하고 경고합니다: 이는 정당한 인증서 갱신이거나, 아니면 제3자에 의한 트래픽 가로채기입니다. 그때 의도적인 조치는 uversion mistrust <url> 후에 다시 연결하는 것입니다.

`uversion logout`

시스템 비밀번호 관리자에서 토큰을 지우고 서버 측에서 이 계정의 모든 세션을 무효화합니다. 토큰이 공유되므로, 이는 데스크톱 클라이언트, Unreal 플러그인, Rider 플러그인도 여러분의 모든 머신에서 로그아웃시킵니다.

$ uversion logout
Logged out (alice)

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

어떤 계정이 동작하는가? 마지막 로그인이 아니라 워크스페이스의 계정

가장 놀라게 되는 지점이며, 무엇이든 스크립트화하기 전에 알아 두는 것이 좋습니다: 사용되는 아이덴티티는 마지막 로그인의 것이 아니라 여러분이 있는 워크스페이스의 것입니다.

워크스페이스란 클론된 폴더로, .uversion 하위 폴더로 알아볼 수 있습니다. 그 안의 .uversion/config.toml 파일에 서버와 소유자 계정이 기록됩니다:

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

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

워크스페이스 안에 있는 한 server_url 과 owner 가 우선합니다: status, checkout, checkin, revert, sync, log, content, lock, info 는 server_url 에 대해 owner 로 인증합니다.

오직 login, logout, repos, clone 만 모든 워크스페이스가 공유하는 설정(Windows에서는 %APPDATA%/uversion/uVersion/config/config.toml)을 사용하며, 이는 데스크톱 클라이언트의 활성 계정을 따릅니다.

이유. 한 대의 머신이 여러 계정에 쓰이는 일이 흔합니다. 예를 들어 두 스튜디오에서 일하는 프리랜서입니다. 이 규칙이 없으면 모든 워크스페이스가 그 순간 활성 계정으로 동작합니다: alice 가 클론했지만 bob 이 활성인 상태에서 사용된 폴더는 잠금을 bob 의 이름으로 걸고, 자신의 파일을 "다른 사람이 잠갔다"고 보며, 업로드가 거부됩니다.

워크스페이스의 아이덴티티를 바꾸려면, .uversion/config.toml 의 owner 필드를 편집하고, 그 계정이 이 머신에서 적어도 한 번 로그인 (uversion login)하여 토큰이 존재하는지 확인하세요. 그런 다음 uversion info 로 실제로 사용되는 계정을 확인하세요.

알려진 제한: 두 서버에서 같은 사용자 이름

토큰은 서버 없이 사용자 이름만으로 저장됩니다. 같은 이름이 서로 다른 두 uVersion 서버에 존재하면, 둘은 하나의 동일한 항목을 공유합니다: 두 번째에 로그인하면 첫 번째의 토큰을 덮어씁니다. 서로 다른 이름을 쓰거나, 한 머신에서는 한 번에 하나의 서버만 사용하세요.

저장소

`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 repos          # si aucun dépôt n'est accessible
No repositories found

`uversion clone`

저장소를 로컬로 가져옵니다. 경로를 생략하면 저장소 이름의 폴더가 현재 디렉터리에 생성됩니다. 클론은 .uversion 하위 폴더도 만들어 폴더를 워크스페이스로 만들고 서버와 소유자 계정을 기록합니다.

전송은 중복 제거를 적용합니다: 내용은 블록으로 나뉘고, 이미 존재하는 블록은 여러 파일에 나타나더라도 한 번만 저장됩니다. 디스크 사용 공간이 다운로드 용량보다 훨씬 작은 경우가 많은 이유입니다.

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...> [--paths-file <fichier>] [--force] [--add] [--json]

옵션	설명
`--paths-file`	파일에서 추가 경로를 한 줄에 하나씩 읽습니다. 대량 경로 목록을 참조.
`--force`	다른 사람이 보유하고 있어도 잠금을 가져옵니다. `force_unlock` 권한을 가진 계정, 즉 `admin` 과 `lead` 역할에 한합니다. 아래 참조.
`--add`	아직 로컬에 없는 경로의 예약을 새 파일용으로 허용합니다.

--force 가 실제로 하는 일

이 옵션은 다른 사람의 잠금을 가져옵니다. force_unlock 권한으로 보호되며, 이는 admin 과 lead 역할이 보유합니다. 그것을 갖지 못한 계정은 명시적 거부를 받으며, 취할 수 있는 조치가 안내됩니다: 관리자에게 요청하거나, 데스크톱 클라이언트의 "해제 요청" 버튼을 사용하세요(해당자에게 알림이 갑니다).

탈취가 실제로 일어났을 때는 감사 로그에 기록됩니다. 관련 경로와 잠금을 빼앗긴 사람의 이름이 함께 기록됩니다. 옵션이 있었지만 다른 사람의 잠금이 아무에게도 넘어가지 않았다면 아무 것도 기록되지 않습니다: 스크립트에서 이 플래그는 흔히 항상 붙어 있고, 무의미한 이벤트로 가득 찬 로그는 아무도 읽지 않는 로그이기 때문입니다.

예:

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

수정된 파일을 업로드하고 단일 트랜잭션으로 서버에 커밋합니다: 전부 통과하거나 아무 것도 통과하지 않습니다. 성공 시 잠금은 자동으로 해제됩니다.

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

옵션	설명
`-m, --message`	커밋 메시지. 필수.
`-a, --all`	인수로 전달한 것뿐 아니라 워크스페이스의 모든 수정된 파일을 포함합니다.
`--paths-file`	파일에서 추가 경로를 한 줄에 하나씩 읽습니다. 대량 경로 목록을 참조.

예:

$ 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...> [--paths-file <fichier>] [--json]

예:

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

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

대량 경로 목록: `--paths-file`

checkout, checkin, revert 는 --paths-file <fichier> 를 받습니다: 한 줄에 하나의 경로를 담은 텍스트 파일입니다. 이렇게 읽힌 경로는 인수로 전달한 것에 더해지며, 대체하지 않습니다.

용도. Unreal 프로젝트에서는 한 작업이 흔히 수천 개의 파일에 걸칩니다. 그것들을 모두 인수로 전달하면 시스템 제한에 부딪힙니다: Windows에서는 명령줄이 32,767자를 넘을 수 없으며, 이는 약 500개의 에셋 경로에 해당합니다. 그 이상이면 명령은 시작되기도 전에 실패하고, 실제 문제에 대해서는 아무 것도 말해 주지 않는 시스템 오류 메시지가 나옵니다. --paths-file 은 이 제한을 없앱니다: 파일에는 필요한 만큼 담을 수 있습니다.

폴더 안의 수정된 파일을, 수와 상관없이 모두 예약하기:

$ 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

그런 다음 정확히 같은 묶음을 업로드하기:

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

Windows에서는 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

이는 Rider 플러그인이 대량의 변경 집합을 전달하기 위해 사용하는 메커니즘이기도 합니다.

`uversion sync`

서버에서 최신 변경을 다운로드하여 로컬 워크스페이스에 적용합니다.

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

플래그	설명
`-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 <numéro_de_révision>] [-o <fichier>]

--revision 은 커밋 해시가 아니라 정수를 기대합니다

이는 파일의 리비전 번호입니다: 첫 버전에서 1, 두 번째에서 2, 이런 식으로 이어지는 카운터입니다. 6e2b8a0 같은 커밋 해시를 전달하면 인수 분석 단계에서 명령이 실패합니다.

번호는 uversion log --path <fichier> 에서 읽을 수 있으며, 각 파일 줄이 괄호 안에 표시합니다. --revision 을 생략하면 최신 버전을 다운로드합니다.

예:

$ 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

히스토리

`uversion log`

현재 저장소의 커밋 히스토리이며, 선택적으로 파일별로 필터링됩니다.

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

플래그	설명
`-n, --limit`	표시할 항목 수(기본값: 20)
`-p, --path`	파일 경로로 필터

예:

$ 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

deleted 로 표시된 줄은 삭제 리비전입니다: 다른 것들처럼 번호를 갖지만 다운로드할 내용은 없습니다.

잠금

잠금은 결코 만료되지 않습니다

명시적으로 해제될 때까지 유지됩니다: uversion checkin, uversion revert, uversion lock release, 또는 관리자의 강제 해제에 의해서. 자동 만료는 존재하지 않습니다. 한 시간 뒤에도, 한 달 뒤에도 없습니다. 예약해 두고 잊은 파일은 누군가 개입할 때까지 그대로 남습니다.

따라서 uversion lock heartbeat 는 아무 것도 연장하지 않습니다. 이 명령은 단지 "이 잠금들을 아직 쓰고 있다"고 말할 뿐이며, 관리자가 활성 잠금과 방치된 잠금을 구분할 수 있도록 하기 위한 것입니다.

`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

표시할 것이 없으면 명령은 No active locks 라고 씁니다.

`uversion lock release`

파일의 로컬 내용을 건드리지 않고 하나 이상의 잠금을 해제합니다. 수정하지 않은 에셋을 "돌려주는" 데 사용하세요: 실수로 예약했거나, 업로드하지 않고 작업을 중단한 경우입니다.

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

예:

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

이 명령은 자신의 잠금만 해제합니다. 다른 사람의 것을 제거하려면 관리를 거치거나, 여러분이 admin 또는 lead 라면 uversion checkout --force 를 사용해야 합니다.

`uversion lock heartbeat`

현재 계정이 보유한 잠금이 아직 사용 중임을 알립니다. 이는 그것들을 연장하지 않습니다: 아무 것도 만료되지 않습니다. 이는 모니터링 신호로, 잠금 목록을 살펴보는 관리자가 어느 것이 아직 활성인지 볼 수 있게 합니다. 일상 작업에는 필요 없지만, 파일을 몇 시간 동안 예약해 두는 자동화 처리에는 유용합니다.

$ uversion lock heartbeat
3 lock(s) extended

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

지속적 통합에서의 예:

$ while build_in_progress; do
    uversion lock heartbeat
    sleep 300
  done

정보

`uversion info`

사용되는 계정과 현재 워크스페이스의 상태를 표시합니다. 무언가 예상치 못하게 동작할 때 가장 먼저 실행할 명령입니다: CLI가 실제로 어떤 아이덴티티로 동작하는지 보여 줍니다. 그것은 워크스페이스 소유자의 것이며, 반드시 여러분의 마지막 로그인의 것은 아닙니다(어떤 계정이 동작하는가? 참조).

$ 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

워크스페이스 밖이거나 유효한 세션이 없을 때:

$ uversion info
User: not logged in

Workspace: not in a uVersion workspace

이 명령은 파일을 세지 않고 변경 요약도 표시하지 않습니다: 그것은 uversion status 의 역할입니다.

JSON output

content 를 제외한 모든 명령은 --json 을 받아 읽기 쉬운 표시를 구조화된 출력으로 바꿉니다. 이것이 CLI를 스크립트화 가능하게 만듭니다.

여러 명령이 루트에 배열을 반환합니다

log, lock list, repos 는 감싸는 객체 없이 직접 JSON 배열을 생성합니다. 따라서 commits 키도, locks 키도, repositories 키도 없습니다: jq 에서 써야 하는 것은 .[] 이지 .commits[] 가 아닙니다. 존재하지 않는 키를 노리는 표현식은 오류 메시지 없이 아무 것도 생성하지 않습니다.

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

status 의 가능한 값:

값	의미
`modified`	파일은 디스크에서 쓰기 가능하며 잠금이 걸려 있지 않음
`locked`	여러분이 예약함
`locked_other`	다른 사람이 예약했으며 `locked_by` 에 이름이 있음
`new`	로컬에 존재하며 서버에는 알려지지 않음
`deleted`	서버에 존재하며 로컬에는 없음
`tracked`	추적되고 온전함. 경로로 필터한 경우에만 나타남

summary.modified 는 modified 와 locked 를 합산한다는 점에 유의하세요. 둘 다 여러분이 작업 중인 파일을 가리키기 때문입니다.

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

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

2126이라는 만료는 오타가 아닙니다: 데이터베이스에서 이 열은 비워 둘 수 없으므로 서버는 100년 뒤로 밀어낸 값을 씁니다. 잠금은 만료되지 않습니다. 이 필드를 사용자에게 표시하지 말고, 그 위에 아무 것도 구축하지 마세요.

오류 처리

실패 시 CLI는 Error: <message> 를 표준 오류 출력에 쓰고 코드 1로 종료합니다. 오류가 표준 출력에 JSON으로 나오는 일은 결코 없습니다: --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"

감사 스크립트: 누가 무엇을 예약했는가?

lock list --json 은 루트에 배열을 반환합니다. 따라서 .[] 로 반복하며, 필드는 username, file_path, acquired_at 입니다:

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

특정 사람이 예약한 파일:

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

커밋 해시 추출

여기서도 배열은 루트에 있고, 필드 이름은 commit_hash 입니다:

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

한 사람의 커밋을, 그 메시지와 함께:

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

워크스페이스를 건드리지 않고 과거 리비전의 에셋 가져오기

uversion content 는 커밋 해시가 아니라 리비전 번호를 기대합니다. 파일의 히스토리에서 찾으세요. 괄호 안에 표시됩니다:

$ 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

또는 한 번에, 파일의 최신 리비전에 대해:

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

지속적 통합에서의 야간 빌드

비밀번호는 -p 가 아니라 UVERSION_PASSWORD 를 통합니다: 프로세스의 명령줄은 머신의 다른 계정이 읽을 수 있기 때문입니다.

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

환경 변수 및 종료 코드

환경 변수

변수	설명
`UVERSION_PASSWORD`	`-p` 옵션이 없을 때 `uversion login` 이 사용하는 비밀번호. 이것이 로그인을 자동화하는 권장 방법입니다: 명령줄 인수와 달리 환경 변수는 머신의 다른 계정에 노출되지 않습니다. 비어 있거나 없으면 CLI는 대화식으로 비밀번호를 묻습니다.
`RUST_LOG`	로그 상세도. 표준 오류 출력에 쓰입니다. 예를 들어 `RUST_LOG=debug`. 기본 레벨: `warn`.

UV_* 변수는 전혀 읽히지 않습니다. 워크스페이스 안에 있을 때 서버와 계정은 .uversion/config.toml 에서, 그렇지 않으면 공유 설정(Windows에서는 %APPDATA%/uversion/uVersion/config/config.toml)에서 옵니다. 세션 토큰은 시스템 비밀번호 관리자에서 옵니다. 어떤 계정이 동작하는가? 참조.

종료 코드

코드	의미
`0`	성공. `--help` 와 `--version` 이 반환하는 코드이기도 하며, 이것들은 오류가 아닙니다.
`1`	모든 애플리케이션 오류: 인증, 권한, 네트워크, 서버, 디스크 쓰기, 워크스페이스 밖, 충돌, 검증. CLI는 종료 코드로 원인을 구분하지 않습니다. 상세는 표준 오류 출력에 있습니다.
`2`	인수 분석 오류: 알 수 없는 옵션, 값 누락, 잘못된 하위 명령.

셸 스크립트에서의 예:

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

설치

치트시트: 모든 명령

인증

uversion login

uversion logout

어떤 계정이 동작하는가? 마지막 로그인이 아니라 워크스페이스의 계정

저장소

uversion repos

uversion clone

파일

uversion status

uversion checkout

uversion checkin

uversion revert

대량 경로 목록: --paths-file

uversion sync

uversion content