Skip to content

Work with lanes

In TOVIO a lane is a landing target, not a workspace. You don't live on a lane the way you do in Git — you live in a change, and a lane is a place finished work lands. Lanes are lightweight mutable pointers, so creating, switching, and deleting them is instant and always safe offline.

Deleting a lane never strands work

tovio lane -d <name> is fully undoable. If you delete the wrong lane, tovio undo brings it back. The work the lane pointed at was never the lane's to lose — it lives in your changes and the object store.

Shipped spellings vs. the designed surface

Creating, listing, and deleting lanes, tovio switch <lane>, and switching straight to a change with tovio switch chg:… all work today. Lane management is spelled tovio lane <name> (create), tovio lane (list), and tovio lane -d <name> (delete). The noun-verb forms in the CLI specification (lane create / list / delete), its --from flag, and the tovio sw short alias are specification-only — a new lane always starts at your current lane's tip.

flowchart LR
    B(["lane<br/>(CRDT pointer)"]) -. "landing target" .- C["chg:001 → chg:002 → chg:003<br/>(where work lives)"]
    C -->|"tovio land --into main"| B

More diagrams for the full day-to-day loop: Branching, committing & merging workflows.

Create a lane

$ tovio lane release-1.2

✓ Created lane release-1.2 at blake3:07afd91f2c…
  → Next: `tovio switch release-1.2` to work on it
  undo with `tovio undo`

The new lane starts from your current position — the tip of the lane you're on. To start a lane from somewhere else, switch there first, then create it.

Creating a lane is O(1) and works fully offline — lanes are CRDT mutable pointers, not copies.

List lanes

$ tovio lane

  feature/cgm-sync  blake3:e36deb9075…
* main  blake3:07afd91f2c…
  release-1.2  blake3:07afd91f2c…

The * marks the lane you're on; each row shows the commit the lane points at. Before the first commit the current lane is listed as (unborn).

Git-compat alias

tovio branch and its short form tovio br are git-compat aliases for tovio lane. They do the same thing and print a one-line note on stderr naming the native verb.

Switch between lanes and changes

tovio switch moves your working copy to another lane — or directly to a change:

$ tovio switch main

✓ Switched to lane main  blake3:07afd91f2c…
  materialized working copy · 0 carried change(s) · 0 conflict(s) · undo with `tovio undo`

Switching to a change works the same way (tovio change switch chg:… is the same operation):

$ tovio switch chg:b8e201

✓ Switched to change chg:b8e201…
  materialized working copy · 0 carried change(s) · 0 conflict(s) · undo with `tovio undo`

Switching never stashes and never loses work. TOVIO snapshots your current change before moving, then three-way merges that snapshot onto the destination: edits that don't overlap the destination are carried along (the carried change(s) count), overlapping edits become ordinary stored conflicts (the conflict(s) count) rather than a refusal, and ignored or untracked files are never overwritten. The switch is one op-log entry, so tovio undo restores both the lane and the exact materialized tree.

Coming from Git?

Git's checkout switched branches, restored files, and created branches all at once. TOVIO splits those jobs apart on purpose: switch moves you, tovio lane <name> makes a lane, tovio restore <file> discards file edits. If you type tovio checkout <lane>, the git-compat layer performs the switch and prints (Git compat:tovio switchmoves between branches.) on stderr; tovio checkout -b <lane> creates the lane first.

Delete a lane

$ tovio lane -d release-1.2

✓ Deleted lane release-1.2
  Reverse with: `tovio undo`

Because a lane is just a pointer, deleting it removes the pointer, not the commits behind it. And it is op-logged, so tovio undo restores it instantly. You can't delete the lane you're on — switch away first.

How lanes and changes fit together

You usually don't make many lanes. The everyday pattern is:

  1. Start work — you're automatically in a change.
  2. Commit as you go; each commit starts the next change.
  3. Land the finished change onto a lane like main.

Because changes know their parent, you can stack them — one change on top of another — without a lane per layer. Landing the bottom change auto-rebases the rest. That stacking model lives in the change workflow; lanes stay simple.

Where to go next

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure