Repository navigation
Locking
Binary assets such as maps, meshes and textures can't be merged, so two people editing one means one of them loses
their work. Vertex prevents that with exclusive locks, taken automatically when you change a file. There is no
p4 edit or checkout step to remember.
While vx is open in a workspace (run vx with no command), it watches the folder and locks each file on the branch
about a second after you save it. The server pushes what others do, so their locked files turn read-only right away
and the session tells you about it:
alice locked Content/Hero.uasset
alice submitted #42 "Fix jump" (3 file(s)). Run 'vx sync' to get it.
Without an open session, vx status (or submit, sync, revert) does the same when you run it. The lock goes
away when you submit the file, revert it, or change it back. Anyone else's copy of a file you hold becomes read-only
the next time their vx talks to the server, and the server refuses to submit a file someone else holds:
! Modified Maps/City.umap (locked by alice on DESKTOP-7; wait for them to submit it, or run 'vx revert Maps/City.umap' to drop your change)
Locks belong to one workspace, so the same person editing a file on two machines is warned too. vx locks shows who
holds what. vx unlock clears a lock left behind by a workspace that no longer exists; anyone with manage
access can clear anyone's. vx status still works offline; it just says it couldn't update locks.
Locks are per branch: a file locked on main can be edited on feature-x. A merge into a branch is blocked for the
paths someone holds there.
Every workspace command runs a lock step after scanning (WorkspaceLocks):
- Files that changed are locked in one batched request.
- Locks on files that are no longer changed (reverted, or changed back) are released.
- Everyone's lock events since the workspace's stored sequence number are applied to the local mirror of the branch's
locks (the
lockstable in.vx/index). - The read-only flag is flipped only on files whose lock state changed. A file you changed locally is never made read-only, and Vertex only clears read-only flags it set itself.
The open session (WorkspaceMonitor) does this live. A FileSystemWatcher records the paths you touch. After 500 ms
of quiet it locks them on their size and timestamp alone, without reading them, so a multi-GB save or a burst of
thousands of files is locked in about a second. It then hashes them and releases any that didn't really change (an
editor that rewrote identical bytes). Activity is held for a second before it's printed, so a quick lock-then-release
isn't reported.
The session subscribes to the project's event stream. Lock and unlock events arrive within moments of being committed, and are applied with the same logic as the lock step. After a disconnect it reconnects with back-off (1 to 60 s) and resumes from the last sequence number it saw, so nothing is missed. Against an older server without the stream, it polls every 60 s.
One-off commands ask the server for lock events since their stored sequence number. When nothing changed, the server
answers from Redis without touching PostgreSQL, which keeps vx status cheap for everyone.
Lock and unlock requests for a project go through a write queue (ProjectWriteQueue): requests that arrive together
run in one transaction with one commit. That transaction locks the project's counters row, the same row a submit
locks, so a submit's "is anything locked by someone else?" check can't race a new lock. Each change appends a
lock.locked or lock.released event in the same transaction, and connected clients are notified after the commit.
See History and revisions and Events.
The metrics vertex_locks_granted_total, vertex_locks_contended_total and vertex_locks_released_total (by
reason: submitted, reverted, unlocked) show locking activity. See Monitoring.
- Best practices for lock etiquette.
-
vx locksandvx unlock.