Explain how history got this way

tovio explain — one verb, several lenses, three output formats.

Written By Dustin

Last updated About 3 hours ago

When something in history is surprising, explain is the debugger. Each lens renders the same explanation document: a stepped terminal narrative by default, a structured tovio.explain/1 JSON document, or a self-contained offline HTML page with a diagram and a gate checklist.

tovio explain <lens> --format human   # default
tovio explain <lens> --format json
tovio explain <lens> --format html > report.html

A global --json always wins over --format.

The lenses for lanes, changes and history

LensAnswers
tovio explain change <chg:>Follow one change id across every amend, rebase, squash and absorb it has been through.
tovio explain dag [A] [B]Ancestor sets, ahead/behind counts, the merge base, generation numbers. Defaults to the current lane against main.
tovio explain lanes [lanes…]The multi-lane timeline — how lanes progress in parallel, branch off and rejoin. --limit caps the generations shown.
tovio explain undoThe local op-log: every operation, the undo/redo head, and the state undo would restore. --limit and --to <op-id>.
tovio explain merge [lane] --into <lane>The merge-process debugger. Prospective by default; --commit <addr> replays a merge that already landed.
tovio explain deps <commit>Why materializing a commit is, or is not, blocked by the dependency gate.
tovio explain sync [lane]The CRDT ref merge: each replica's stamped candidate, which won, and why.
tovio explain semantic [A] [B]The symbol-graph diff and the semantic-check = required gate.

The two you will use most

tovio explain change chg:a3f7b2
tovio explain undo

The first answers "the hash changed — is this still my change?" The second answers "what exactly will tovio undo do, and how far back can I go?" — including the op-ids tovio undo --to <op-id> takes.

Reading it, not guessing at it

Every lens is read-only and computed from local objects and the local op-log. Nothing is inferred, and nothing is written — so it is always safe to run, including mid-conflict and mid-bisect.

tovio land --explain
tovio health --explain

The same merge trace, reached from the command you were already running.