Repository navigation
Concepts
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.
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).
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.
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.
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.
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.
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.
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.
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 | 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 |