Explain — ask TOVIO to explain itself¶

Every TOVIO operation is a pure, deterministic decision: a merge resolves, a lane pointer converges, a pull is gated, a plugin passes or vetoes. Normally you only see the one-line verdict — clean, 3 conflicts, blocked. The reasoning that got there is thrown away.

tovio explain gives it back. It re-runs the decision read-only and shows you every step: what it compared, which check passed, where two lanes diverged, and — for anything that went a way you didn't expect — why. Think of it as "TOVIO, explain yourself."

Read-only, always

explain never changes your repository — it takes no locks and advances no refs. Run it as often as you like, before or after an operation, to understand what TOVIO did or would do. It's the safe way to poke at anything.

What's shipped

Ten lenses ship today — merge, lanes, sync, deps, rerere, dag, change, semantic, plugin, and undo — each in three formats (terminal, --json, and a self-contained HTML page). The merge lens reuses the real land pipeline's read-only helpers, so its verdict matches an actual land.

Why you'd use it¶

Version control tools are usually black boxes: they make a call and hand you a result. When the result surprises you — "why did that conflict?", "why is my lane behind?", "why won't this pull?", "why didn't my saved resolution stick?" — you're left guessing.

explain answers those questions directly. It's for the moment you think "wait, why did it do that?" — and for learning how TOVIO actually works by watching it decide on your own repo.

How it works¶

One idea, applied to every subsystem: replay the decision read-only, capture a structured trace, render it three ways.

flowchart LR
    OP["a TOVIO decision<br/>(merge, sync, gate, …)"] --> R["explain replays it<br/>(read-only)"]
    R --> T["one structured trace"]
    T --> A["terminal<br/>scannable"]
    T --> B["--json<br/>machine contract"]
    T --> C["--format html<br/>shareable page"]

Because the trace carries no clocks or authors — only stable Change IDs, addresses, and paths — two runs of the same explain are byte-identical. The --json output is a clean machine contract (no emoji, no prose), and the HTML page is a reproducible artifact you can share in a review.

The lenses¶

Each lens is one subsystem's debugger. Pick the one that matches your question:

Lens	Answers	Try
`merge`	How would this land resolve? What auto-merges, what conflicts, what checks gate it?	`tovio explain merge my-lane --into main`
`lanes`	How do my lanes progress in parallel, where did they branch, where did they rejoin?	`tovio explain lanes`
`sync`	Why does this lane point where it does after syncing? Who won and why?	`tovio explain sync main`
`deps`	Why is this pull blocked (`TVO-CONFLICT-004`), and what would `--isolate` do?	`tovio explain deps <commit>`
`rerere`	Why didn't my saved conflict resolution replay?	`tovio explain rerere`
`dag`	How do two points in history relate — ahead/behind, common ancestor?	`tovio explain dag my-lane main`
`change`	Where did my change go across amend / rebase / squash?	`tovio explain change chg:…`
`semantic`	Did an interface change break something a text diff would miss?	`tovio explain semantic`
`plugin`	Which lifecycle plugins are wired, and can any of them block me?	`tovio explain plugin`
`undo`	What has happened, and exactly what would `undo` restore?	`tovio explain undo`

Every lens produces the same self-teaching page: a what this shows intro, a plain-English summary of the finding, the detailed trace with per-stage hints, a what to do next panel with the exact commands, and a glossary of any jargon.

See your lanes diverge¶

The lanes lens is the one the docs never had a picture for: a multi-lane timeline where every lane is a row, time runs left→right, dashed lines mark where a lane branched off (a fork), solid lines mark where a land rejoined them (a merge), and glowing dots are the lane tips.

See it worked through, with the real output embedded: Seeing lanes diverge: the lane timeline.

Render your own — a self-contained, offline page:

$ tovio explain lanes --format html > lanes.html

Three ways to read it¶

TerminalJSONHTML

The default. Answer first (verdict + plain English), then the detailed trace, then what to do next.

$ tovio explain merge feature --into main

Merge trace
  `feature` → `main`  (prospective)
  …
  Verdict: 1 conflict(s) stored — your work keeps moving. Resolve when ready: `tovio resolve`

  In plain English
  `feature` and `main` diverged and 1 file(s) conflict. The land still succeeds —
  the conflicts are stored as first-class objects and your work keeps moving.
  Resolve them whenever you're ready.

── Stage 4 · Per-file decisions ──────────────────────────
  What happened to each changed file: taken from one side, auto-merged, replayed, or conflicted.
  ✓ src/app.rs                         auto-merged (line algebra)
  ⚠ config.toml                        conflict (content) — resolvable

  What to do next
  → Land now (stores the conflicts)  tovio land feature --into main
  → Resolve the conflicts  tovio resolve
  → See all open conflicts  tovio conflicts

  reproduce: tovio explain merge feature --into main

A clean machine contract for scripts and tooling (schema tovio.explain/1). No glyphs, no prose — just data.

$ tovio explain merge feature --into main --format json

{ "result": {
    "schema": "tovio.explain/1", "lens": "merge",
    "badge": { "level": "ok", "text": "1 conflict(s) stored — your work keeps moving…" },
    "stages": [ … ], "gates": [ … ], "next_steps": [ … ],
    "command": "tovio explain merge feature --into main" } }

A shareable, self-teaching page — the diagram, the trace, the gate checklist, a glossary, and the exact reproduce command. Great for a review or an incident write-up.

$ tovio explain merge feature --into main --format html > merge.html

A shortcut on `land` and `health`¶

You don't always need the full command. The merge lens is one flag away on the verbs you already use:

$ tovio land feature --into main --dry-run --explain   # trace the land without doing it
$ tovio land feature --into main --explain             # trace it, then land for real
$ tovio health --into main --explain                   # same trace, from health

Try it¶

$ tovio explain lanes                       # see all your lanes on one timeline
$ tovio explain merge my-lane --into main   # why would this land the way it does?
$ tovio explain undo                        # what would undo restore?
$ tovio explain sync main                   # who won the last ref-merge, and why?

Where to go next¶

Land a change — the verb the merge lens explains.
Resolve conflicts — what a stored conflict is, and how the rerere lens helps.
Lanes — the model the lanes timeline visualizes.
Command reference: tovio explain — every lens and flag.

Last reviewed September 9, 2026

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