Skip to content

Locking

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

File 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.

How it works for you

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.

How it works inside

Taking locks

Every workspace command runs a lock step after scanning (WorkspaceLocks):

  1. Files that changed are locked in one batched request.
  2. Locks on files that are no longer changed (reverted, or changed back) are released.
  3. Everyone's lock events since the workspace's stored sequence number are applied to the local mirror of the branch's locks (the locks table in .vx/index).
  4. 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.

Seeing others' locks

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.

On the server

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.

See also

Clone this wiki locally