Check and compact the repository: fsck and gc

Everyday repository maintenance, and what each command will and will not touch.

Written By Dustin

Last updated About 3 hours ago

Two maintenance commands. Neither is something you run daily, but both are worth knowing before you need them.

Check integrity

tovio fsck

Re-hashes every object, verifies references, and verifies the per-actor signed audit chain. It also scans for private-key material that should never be in the object store.

It exits 0 only when no structural problem is found. A failure is TVO-STORE-004 (exit 7) and lists every problem: corrupt or malformed objects, broken references such as dangling refs or truncated history, or a broken audit chain. Suspected key material is an advisory warning — reported, but still exit 0.

FlagWhat it does
--strictPromote key-material warnings to failures. This is the zero-tolerance CI gate.
--repairAlso reconcile an interrupted commit left pending by a crash against its journal, so a repository that refuses to open can be reopened. Opt-in, because it takes the repository write lock — the default passes are read-only.

The --json report carries ok, strict, objects_checked, kinds_checked, refs_checked, audit_entries_verified, and three arrays: problems, warnings, and promised (objects a partial clone has not fetched — informational and re-fetchable, never a failure).

Where that report sits depends on the outcome, and it catches scripts out. A clean store prints it as the top-level result and exits 0. A failing store carries the same report as the error envelope's context and exits 7 — one JSON document either way, never both. So a CI check should read the exit status first, then .context.problems on failure rather than .problems.

Reclaim space

tovio gc
tovio gc --dry-run

Garbage-collects unreferenced objects. It is deliberately conservative: an object is removed only when it is reachable from no ref, no tag, and no op-log entry. That last condition is what keeps tovio undo and tovio redo intact across a collection. Obliteration tombstones are never removed.

FlagWhat it does
--dry-runReport what would be reclaimed, delete nothing.
--repackAfter reclaiming, fold the surviving loose objects into a pack.
--explodeUnpack every pack back to loose objects — the pre-pack-format downgrade.
--aggressiveFull compaction: unpack, prune, repack. On a partial (promisor) clone it also drops re-fetchable backfills.
--autoMaintenance-if-needed: prune and repack only once the loose store has grown past a threshold, otherwise a fast no-op.

--repack, --explode, --aggressive and --auto are mutually exclusive. The --json report includes pruned, reclaimed_bytes, repacked, exploded and dry_run.

Which one to reach for

SymptomCommand
A command reported a hash mismatch or corruptiontovio fsck, then re-fetch the named objects
The repository will not open after a crashtovio fsck --repair
.tovio/objects has grown largetovio gc --dry-run, then tovio gc --repack
A scheduled hygiene job in CItovio fsck --strict and tovio gc --auto

Both commands are Advanced-tier, so they are hidden from the default tovio help index. They still run — tovio help --all lists them.