Skip to content

Concepts

Kyle Ebbinga edited this page Nov 19, 2026 · 1 revision

Server

One Vertex deployment. It keeps metadata (projects, branches, revisions, locks, users) in PostgreSQL and file content in S3-compatible storage, with Redis as an optional cache. Server instances are stateless so that you can run several behind a load balancer. See Architecture.

Project

A named collection of files with its own history, branches, locks, and access grants, like a git repository or a Perforce depot. Create one with vx init (which also creates a workspace).

Writes to one project (submits, merges, lock changes) are applied one transaction at a time. That keeps history linear and lock checks exact, and it means a project has a write-throughput limit. Unrelated teams belong in separate projects (see Best practices).

Workspace

A folder on your machine linked to a project and one of its branches, marked by a .vx/ folder at its root (like .git/). .vx/ holds:

  • config: the server, project, branch, and workspace ID.
  • index: a SQLite database of known files (size, timestamp, content id), the last synced revision and a mirror of the branch's locks.

There is no local history. You can't commit offline or diff against old revisions without the server. In exchange, a workspace is cheap: a 200 GB project needs 200 GB on disk, not more. Commands find the workspace by walking up from the current folder, so they work from any subfolder. See Workspaces.

Branch

A named line of history inside a project. A new branch starts as a server-side copy of its parent's files, so creating one costs no uploads. Each workspace follows one branch. vx checkout switches it, downloading only the files that differ. A branch can have a merge target: every revision on it is then automatically merged into that branch. See Branching and merging.

Revision

The unit of history is written as #N. vx submit turns your changes into a single revision, and vx merge writes it to the target branch. Revision numbers count up per project across all its branches, so #42 names exactly one revision in the project. Each revision records who submitted it, from which machine, when, the message, and every file it added, changed, or deleted.

A submit is refused when one of its files changed on the server since your last sync. Vertex is designed with binary files in mind and never merges file content, so you sync first and submit on top of the latest version.

Head

A branch's latest file list: for each path, the content ID of the newest version. vx sync compares your workspace's synced revision with the head and downloads only what differs.

Content ID

Files are identified by their content, not their path. A file is split into chunks, and each chunk is named by a SHA-256 hash. The file's ID is a hash of its chunk list. The same bytes are stored once, regardless of how many files, branches, or projects use them. See Storage.

Lock

An exclusive claim on a file on a branch, held by one workspace. Vertex locks a file when you change it (no checkout step), and releases it when you submit, revert, or change it back. Files others hold are read-only in your workspace. See File locking.

Events

Everything others may react to (locks, revisions, merges) is recorded as a project event and pushed to connected clients. That's how an open vx session learns about others' locks within moments. See Events.

Vertex, git and Perforce

Vertex git Perforce
Server Remote (but history is local) Server (P4PORT)
Project Repository Depot / stream depot
Workspace (.vx/) Clone (.git/) Client workspace (client spec)
Branch Branch Stream / branch
Revision #N Commit Changelist
vx submit git add -A && git commit && git push p4 reconcile && p4 submit
vx sync git pull p4 sync
vx sync -r 120 git checkout <sha> p4 sync @120
vx revert git restore p4 revert
vx checkout git switch p4 switch
vx merge git merge (file level only) p4 integrate && p4 resolve && p4 submit
Automatic lock on change (Git LFS locks, by hand) p4 edit with +l file type
.vxignore .gitignore .p4ignore

Clone this wiki locally