A solo project, end to end¶

In this tutorial you will run a real solo workflow from start to finish: start a repository, do some work on a lane, switch between lines of work without dropping tracked state, land a change onto main — and then undo that recorded local land, to see the op-log recovery model in action.

By the end you'll understand the daily loop and which supported local mutations the op-log can reverse.

Before you start

You'll want the quickstart under your belt — this tutorial assumes you know init, commit, status, and log. All commands here are part of the runnable offline core.

The mental model in one minute¶

Two ideas make TOVIO feel different from Git. Keep them in mind:

You work in a change, not on a lane. A change is your current unit of work, with a stable name (chg:…) that survives every rewrite. A lane is a destination you land finished work onto — not the place you live while you work.
Supported local mutations are op-logged. Not just commits — lane deletes, lands, rewrites, and the local side of sync have reversible entries. tovio undo restores the previous local state.

The full picture is in Core concepts; this tutorial is the feeling.

Step 1 — Start a project¶

mkdir notes-app && cd notes-app
tovio init
echo "# Notes App" > README.md
tovio commit -m "Start the project"

✓ committed  chg:g12snkjmk2948j0hb6s0a23n5r  blake3:fa41c41cd7…
  1 file(s) · new change chg:61wvtd1php75mpfqjd9ash660g · undo with `tovio undo`
  → Next: `tovio log` to review, or `tovio branch <name>` to start a feature

You're on main, with one commit and a fresh change ready to go. (tovio branch in that hint is the Git-compat spelling of tovio lane — it works, and says so when you use it. Turn the hints off entirely with tovio config set ui.hints off.)

Step 2 — Make a lane for a feature¶

Lanes in TOVIO are cheap, O(1), and always safe to create offline. Make one for a feature:

tovio lane search-feature
tovio switch search-feature

✓ Created lane search-feature at blake3:fa41c41cd7…
  → Next: `tovio switch search-feature` to work on it
  undo with `tovio undo`
✓ Switched to lane search-feature  blake3:fa41c41cd7…
  materialized working copy · 0 carried change(s) · 0 conflict(s) · undo with `tovio undo`

Coming from Git?

tovio switch does exactly one thing — move you to another lane or change. It is the single-purpose replacement for Git's overloaded checkout. If you type tovio checkout out of habit, TOVIO redirects you here with a gentle note.

Now do some work and commit it:

echo "fn search() {}" > search.rs
tovio commit -m "Add search skeleton"

✓ committed  chg:61wvtd1php75mpfqjd9ash660g  blake3:08c909e82e…
  2 file(s) · new change chg:6zvc2v6g40gcn1erp2et7ns624 · undo with `tovio undo`
  → Next: `tovio land` to merge onto main, or `tovio log` to review

The 2 file(s) is the whole tracked snapshot — README.md and search.rs — not the size of the diff. TOVIO commits complete trees; tovio diff is what shows you the delta.

Step 3 — Switch lines of work, lose nothing¶

Say something urgent comes up on main. In Git you'd git stash first. In TOVIO you just switch — your in-progress work is snapshotted into its change automatically, and it's waiting for you when you come back.

tovio switch main
# ...fix the urgent thing...
echo "fixed" > hotfix.txt
tovio commit -m "Urgent hotfix"
tovio switch search-feature   # your search work is exactly as you left it

No stashing, ever

Switching between changes or lanes never requires stashing and never loses working-copy state. The change you're leaving is snapshotted first, so you can move freely and return to precisely where you were.

Step 4 — Check the change is healthy¶

Before you land work, ask whether it's clean and ready. tovio health is a read-only diagnostic — it reports, it never mutates anything.

tovio health

Change health — `search-feature` landing into `main`
  conflicts:  none ✓
  staleness:  1 commit(s) behind main · 0 days old
  semantic:   none ✓
  landable:   yes ✓ (2 changed file(s) merge cleanly)

Landable, no conflicts — this is ready. (One commit behind main is the hotfix you just made; a land merges over it cleanly.)

Step 5 — Land the work onto `main`¶

tovio land is the everyday "ship this" verb: it integrates your change onto a lane.

tovio land --into main

✓ landed `search-feature` into `main`  blake3:ef2c5946b4…
  2 file(s) merged · same Change IDs — your work kept its identity · undo with `tovio undo`

Two things worth noticing:

The land preserved the change's identity. Landing (like rebasing) produces a new commit hash, but the chg:… ID is unchanged — so you, your CI, and your teammates can always point at the same change no matter how its history moves.
TOVIO told you, right there, how to undo it.

Protected lanes refuse unresolved conflicts — and that's a feature

A solo repository has no protected lanes unless you declare one, so by default a land that cannot auto-merge still succeeds and says so:

✓ landed `feature` into `main` with 1 conflict(s)  blake3:b82461932f…
    ⚠ content       f.txt

  nothing is blocked — the conflicts are stored as data.
  resolve them:   tovio resolve
  list them:      tovio status --conflicts

Declare the lane protected with a review requirement — tovio policy protect main --require-review — and the same land is refused instead, because a protected lane must stay buildable:

✗ Cannot land: 1 unresolved conflict(s)

  Landing `feature` into protected `main` leaves 1 unresolved conflict(s):
    content       f.txt

  See where the branch stands:
    tovio health
  List the conflicts:
    tovio status --conflicts

This is safe to bump into — it never loses work, it just tells you to resolve first.

Step 6 — Undo the recorded land¶

Now the payoff. Changed your mind about that land? Take it back.

This local land is reversible

tovio undo reverses the last operation — and land is one operation, cascade included. You return to its recorded pre-land local state. If you change your mind again, tovio redo puts the land back.

tovio undo

✓ Undid: land search-feature into main
  Redo with: `tovio redo`

main is back to where it was, and your change is intact. Try it the other way too:

tovio redo      # puts the land back
tovio undo      # and takes it away again

This is not just for commits. Supported local mutations such as lane deletes, lands, rewrites, and the local effects of a sync are represented in the op-log while their entries are retained. To see the log itself — every operation, where you are in it, and what the next undo would restore — run tovio explain undo.

Undo is local, not a recall mechanism

Undoing a sync restores the recorded local repository state; it does not recall objects or ref observations already received by peers. Explicit irreversible maintenance such as authenticated obliteration, external service effects, and operations outside the retained op-log are not reversed.

Undo a lane delete, to prove the point

tovio lane experiment
tovio lane experiment -d   # delete it
tovio undo                   # and it's back

✓ Undid: delete lane experiment
  Redo with: `tovio redo`

Deleting a lane never strands work, because the delete is just another undoable operation.

What you learned¶

You work in changes; you land onto lanes.
Switching lines of work never stashes and never loses your state.
History rewrites (land, rebase) preserve the change's stable ID — the cure for rebase anxiety.
tovio undo reverses the latest supported retained local op-log entry, and tovio redo replays it.

That last point is the recovery model TOVIO emphasizes: recorded local mutations have an explicit way back, within the documented op-log and external-side-effect boundaries.

Next¶

You've mastered the solo loop. Now the feature that makes TOVIO unlike any other VCS — a secret that stays encrypted even when someone clones your entire repo.

Protect a secret

Last reviewed September 9, 2026

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