Quickstart: your first repository¶

In this tutorial you will create a TOVIO repository, make a change, save it, and look at its history — the whole loop, in under a minute. There is no key setup, no identity ceremony, and no staging area to learn first. You just init, edit, and commit.

Before you start

You need the tovio binary on your PATH. If you don't have it yet, do the install tutorial first (about five minutes).

The whole loop, first¶

Here is everything you are about to do. The rest of the page walks each step.

mkdir my-project && cd my-project
tovio init                    # create the repo in this directory
echo "fn main() {}" > main.rs # edit a file (tracked automatically — no `add`)
tovio status                  # see what's tracked
tovio commit -m "Initial commit"
tovio log                     # browse history

Step 1 — Create the repository¶

tovio init initializes the current directory, so make one and step into it first:

mkdir my-project && cd my-project
tovio init

✓ Initialized empty TOVIO repository in /path/to/my-project/.tovio
  On branch main · current change chg:4hvey7vcyrk0gbhj6pcr95j7mg · mode: simple
  → Next: edit files, then `tovio commit -m "…"`

That's it. In Simple Mode there is no key to create, no algorithm to pick, and no wall of questions — the repository is ready to commit. (A cryptographic identity is provisioned when you first need one: --mode team, or later with tovio identity init.)

Simple Mode is the default

On an interactive terminal, tovio init asks exactly one question — who will work on this repo — and defaults to Just me (Simple Mode) if you press Enter. In Simple Mode there is no Key Authority and no policies; the word "encryption" never appears until you reach for it. You can skip the question entirely with tovio init --mode simple (the other answers are team and agentic).

Step 2 — Edit a file¶

Create a file. Any file — TOVIO tracks your working copy automatically.

echo "fn main() {}" > main.rs

There is no tovio add

Coming from Git, this is the first habit to unlearn. TOVIO has no staging area. Your working copy is the current change, tracked continuously. You never add a file before committing it. (If muscle memory makes you type tovio add, TOVIO won't error — it gently reminds you that tracking is automatic.)

Step 3 — See what's tracked¶

tovio status is your source of truth — any time you're unsure of the repo's state, ask it.

tovio status

  on main · chg:4hvey7vcyrk0gbhj6pcr95j7mg
  (no commits yet)
  modified (1 file(s))
    + main.rs

Notice the change ID (chg:4hvey7…). A change is your current unit of work. It gets a stable name the moment the repository exists — and that name will never change, even if you later rewrite its history. You don't create it with a command; it's just there, tracking what you do.

Step 4 — Commit¶

Save the change into a permanent snapshot:

tovio commit -m "Initial commit"

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

Two things to note:

TOVIO started a fresh change for you automatically (chg:nwxdgj…). You're always already in a change, ready to keep working.
Reversible mutations name tovio undo. The guarantee is scoped to supported entries retained in this repository's local operation log; irreversible maintenance and external side effects are not recalled by it.

No message? TOVIO prompts you

If you run tovio commit without -m in a terminal, TOVIO opens a friendly prompt showing what's in the change and its ID, then asks for a message — not a blank editor. (In scripts and with --json or --quiet, -m is required.)

Step 5 — Browse history¶

tovio log

@ chg:4hvey7vcyrk0gbhj6pcr95j7mg  (main)
  Initial commit
  you · just now · blake3:d440efe85c…

You did it: a tracked, committed, content-addressed repository — and you never touched a key.

What just happened¶

You ran	And TOVIO…
`tovio init`	Created the repo in the current directory, ready to commit
(edit a file)	Tracked it automatically — no staging
`tovio status`	Told you the current lane, change, and what's modified
`tovio commit -m`	Saved an immutable snapshot and started your next change
`tovio log`	Showed history, keyed by stable change IDs

Next¶

You've done the loop. Now do a real project: create a lane, switch between lines of work, land a change onto main, and undo something you thought was gone.

A solo project, end to end

Prefer to be walked through it interactively?

TOVIO ships a guided, in-terminal tutorial — the cargo new of TOVIO. It creates a throwaway scratch repository, shows each command, runs it, and reminds you that every step is reversible with tovio undo:

tovio quickstart                     # basics: track a file, commit, browse history
tovio quickstart --topic branches    # lanes and switching
tovio quickstart --topic conflicts   # land a conflict, see it stored not blocked
tovio quickstart --topic policy      # protect a path and commit a sealed secret

The scratch repository is removed on exit (pass --no-cleanup to keep it).

Last reviewed September 9, 2026

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