Lock a binary file so nobody else edits it

tovio lock <path> --ttl 2h --exclusivetovio lock <path> --ttl 30m --advisory --reason 'rebaking lightmaps'tovio unlock <path>tovio locks

Why locks exist at all

Three-way merge works on text. A binary asset — a PSD, a scene file, a compiled model — cannot be merged, so two people editing one produces work that must be thrown away. A lock prevents the collision rather than resolving it.

Exclusive versus advisory

Omit both and the lock takes whatever kind the policy declares for that path. Passing one overrides the declaration, which is how you take a softer advisory lock on an exclusive-declared path.

The path has to be declared lockable

Locking is opt-in per path pattern, never the default, and never applies to mergeable text. A path matching no lockable declaration in the policy manifest is refused with TVO-LOCK-003. See the article on deciding which paths are lockable.

Always set a TTL

--ttl is required, and it takes a duration like 30m, 1h, or 2d. The lock auto-releases when it expires. A lock without expiry would be a lock someone has to break after that person leaves.

Who actually arbitrates

A local record alone cannot arbitrate across machines, so when a default Forge is configured — the remote named origin, or the origin recorded at clone — tovio lock acquires the authoritative lock there, as your signed principal. Your identity is taken from the signature; it is never a field in the request.

A refusal that is a decision rather than an outage — a stale proof, an authorization denial — hard-blocks. It never falls back to a local lock.

What is enforced when you land

Two separate gates run at land time, and they answer different questions.

• Divergence, regardless of who holds what. If an exclusive-lockable path was edited divergently on both sides, the land is refused with TVO-LOCK-002. A binary is never folded into a conflict object, because the later write would simply be lost. This also fires for a change rebase, split, or absorb whose re-derivation leaves a conflict on such a path.
• The holder-aware write guard. Before the ref advances, every exclusive-lockable path the land writes that you do not already hold is acquired at the Forge for a short window. Another holder blocks it with TVO-LOCK-001; an unreachable Forge warns and proceeds on local state, so an outage never hard-blocks a land.

The gap to plan around

Both gates above live in the client, on tovio land. A plain tovio push or tovio sync does not consult the lock store, and neither does a Forge's own land path when a proposal is landed server-side. So the guarantee is only as good as everyone landing through tovio land. Treat locks as strong coordination among people running the CLI, not as a gate the server enforces on your behalf, and keep unmergeable assets on lanes that land locally.

Seeing what is held

tovio lockstovio forge lock list --remote <host:port>

tovio locks is your machine's last-known view, with expired entries pruned as it reads. The Forge's list is the authoritative one, showing each lock's path, holder, kind, and TTL window.