Skip to content

Commit your work

A commit finalizes the current change into an immutable snapshot and starts the next change automatically. There is no staging area and no tovio add — TOVIO tracks your working copy as the current change continuously, so everything you've edited is already in. You commit when a unit of work is done, not to "stage" it first.

This commit is recorded and reversible

Right after committing, tovio undo returns your local working tree and repository state to the state before that commit. See Undo and redo recorded operations.

What works today

tovio commit -m "<message>", the interactive prompt (commit without -m), and --amend are all in the shipped CLI. One flag on this page — --intent — is specification-only: it describes the designed surface, not a flag you can run yet. The standalone tovio amend spelling is also specification-only; tovio commit --amend is the shipped form.

flowchart LR
    E["edit<br/>(auto-tracked)"] --> C["tovio commit -m"] --> F(["✓ chg:a3f7 finalized"]) --> N["chg:b8e2<br/>(next change, auto-started)"]

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

Commit with a message

To save the current change, give it a message:

$ tovio commit -m "Add Dexcom G7 sync handler"

✓ committed  chg:a3f7b2…  blake3:19d787680b…
  2 file(s) · new change chg:b8e201… · undo with `tovio undo`

Two things just happened:

  1. The change chg:a3f7b2… was finalized into an immutable commit (blake3:… is the commit's content address). Its Change ID stays the same no matter how you rewrite its history later.
  2. A fresh change (chg:b8e201…) was started for you. You're already in it — keep editing.

You never run tovio add. Everything tovio status listed as modified is part of the commit. (Real Change IDs are 26 base32 characters; the ones on this page are shortened for reading.)

Commit interactively (no -m)

If you omit -m at an interactive terminal, commit asks for the message in place — not in a blank editor. It names the change being finalized and how many files it carries:

$ tovio commit

  committing chg:a3f7b2… · 2 file(s)
  Message: _

An empty message is refused the same way a missing -m is (TVO-CLI-019).

In scripts, -m is required

With --json, --quiet, or no terminal attached, commit can't prompt, so it requires -m. Without it you get TVO-CLI-019 — This commit needs a message (a usage error, exit code 2) with the remediation tovio commit -m "<message>". This keeps the machine contract predictable.

Record intent alongside the message

--intent is designed to record a structured, natural-language why next to the what: the message says what changed; the intent captures the reasoning, which travels with the commit and shows up in tovio log.

Not yet available

--intent is in the CLI specification but not in the shipped grammar — tovio commit --intent is rejected today. The shipped way to attach reasoning is tovio log --why's rationale object, authored today through tovio resolve --why (Resolve conflicts).

Fold edits into the current change (--amend)

If you want to add more edits (or fix the message) without starting a new change, amend instead of committing:

$ tovio commit --amend -m "Add Dexcom G7 sync handler (with retry)"

✓ amended  chg:a3f7b2…  blake3:07afd91f2c…
  2 file(s) · amended · undo with `tovio undo`

--amend folds the current working change into the last commit and preserves its Change ID. With -m it rewrites the message; without -m the existing message is kept. It is refused on a lane with no commits yet. Amending is a history rewrite, and like every rewrite in TOVIO it keeps the change's identity intact — see Rewrite history safely.

The --json form

$ tovio commit -m "Add Dexcom G7 sync handler" --json

{
  "result": {
    "change": "chg:a3f7b2…",
    "commit": "blake3:…",
    "files": 2,
    "next_change": "chg:b8e201…"
  }
}

The JSON envelope reports the finalized Change ID, its commit address, the file count, and the new change started in its place ("amended": true replaces next_change on an amend), with no glyphs or warmth lines — that decoration is human-terminal only.

There is no ci commit alias

tovio ci is the CI/CD subcommand group (tovio ci check, tovio ci compile), not a commit alias. tovio ci -m "…" is a parse error — use tovio commit -m "…".

Where to go next

Last reviewed September 9, 2026

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