Configuration¶

The on-disk layout of a TOVIO repository, its two configuration files, and .tovioignore. A repository keeps them apart on purpose: .tovio/config.toml is operational state written at init, while .tovio/config holds the preferences tovio config edits. For what the git-compat keys switch off, see git-compat aliases.

The `.tovio/` directory¶

Every repository keeps its state under a single .tovio/ directory at the repository root. The content- addressed object store, refs, op-log, identity material, and the working-copy index all live here.

.tovio/
├── format                      # single line: "tovio-format 1" — the format-version marker
├── config.toml                 # replica-local operational config (mode; [ref_tombstones], [gc], [line_ops])
├── config                      # local UI / compatibility preferences — what `tovio config` reads and writes
├── identity/                   # local identity key material (encrypted at rest)
│   └── default.key
├── objects/                    # content-addressed store, sharded by address prefix
│   ├── blob/<aa>/<rest>
│   ├── chunk/<aa>/<rest>
│   ├── chunk-manifest/<aa>/<rest>
│   ├── tree/<aa>/<rest>
│   ├── commit/<aa>/<rest>
│   ├── policy-blob/<aa>/<rest>
│   ├── policy-chunk/<aa>/<rest>
│   ├── conflict/<aa>/<rest>
│   ├── behavioral/<aa>/<rest>
│   ├── audit-entry/<aa>/<rest>
│   ├── obliteration/<aa>/<rest>
│   ├── policy-manifest/<aa>/<rest>
│   ├── capability/<aa>/<rest>
│   ├── symbol-shard/<aa>/<rest>         # symbol-graph artifacts (sealed-symbol-shard for
│   ├── symbol-xref/<aa>/<rest>          #   a protected path; symbol-xref is the projection)
│   ├── sealed-symbol-shard/<aa>/<rest>
│   ├── rationale/<aa>/<rest>            # attested deliberation provenance
│   └── pack/                            # optional packing layer — same addresses, fewer files
├── refs/                       # CRDT mutable state
│   ├── heads/                  # local lane registers
│   ├── tags/                   # immutable tag refs
│   └── remotes/                # remote-tracking CRDT state
├── op-log/                     # local operation log (NOT synced) — backs `tovio undo`
├── policies/                   # working copy of policy manifests
├── keys/                       # local cache of attribute-derived / wrapped keys (encrypted at rest)
├── working-copy/
│   ├── HEAD                    # the current lane's name
│   ├── current                 # the current change id
│   └── tracking.idx            # path → (size, mtime, kind, digest, mode) stat cache
└── semantic/                   # optional symbol graph + behavioral registry
    ├── symbols.db
    └── behavioral-versions/

Path	What it holds
`format`	The format-version marker. This document describes version 1.
`config.toml`	Replica-local operational configuration (see below). Never synced.
`config`	Local UI and compatibility preferences — the file `tovio config` reads and writes.
`identity/`	Local identity private keys, encrypted at rest via the OS keychain.
`objects/`	The content-addressed store, segregated by object type and sharded by address prefix.
`refs/`	CRDT mutable refs: local lanes (`heads/`), immutable `tags/`, and remote-tracking state.
`op-log/`	The local, append-only operation log. Backs `undo` / `redo`. Never synced.
`policies/`	A working copy of the policy manifests (mirrors the `policy-manifest` objects).
`keys/`	A local cache of wrapped / attribute-derived keys, encrypted at rest. Never synced.
`working-copy/`	The current change pointer (`HEAD`) and the path-snapshot cache (`tracking.idx`).
`semantic/`	The optional symbol graph and behavioral-version registry.

No key material in objects/

Identity private keys and cached wrapped keys live encrypted at rest under identity/ and keys/, using the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) for the wrapping key. No key material is ever written to objects/ — secrets never enter the synced object store. This is a hard invariant checked by tovio fsck and CI.

Object-store sharding¶

Objects are addressed by the BLAKE3-256 hash of their canonical bytes. Within each type directory, <aa> is the first byte of the address as two hex chars and <rest> is the remaining 31 bytes — this caps directory fan-out. The type directory (blob/, commit/, …) is authoritative for blob and chunk, which carry no inline type tag.

`config.toml`¶

.tovio/config.toml is replica-local operational configuration — it is never synced, and it is written by tovio init rather than by hand. It carries the top-level mode (the protection tier this replica seals at) plus three optional tables:

Table	Key	Default	Meaning
`[ref_tombstones]`	`enabled`	`false`	Opt in to causal ref-tombstone pruning.
`[ref_tombstones]`	`retention_seconds`	`2592000` (30 days)	How long a tombstone is retained before it may be pruned.
`[ref_tombstones]`	`replicas`	`[]`	The replica set whose receipts a prune must see first.
`[gc]`	`reach_bitmaps`	`false`	Opt in to the reach-bitmap `gc` accelerator (same keep-set, faster enumeration).
`[line_ops]`	`strict`	`false`	Turn an advisory missed line-op capture into a refused commit.

Parsing is fail-closed: a malformed file fails the command that reads it rather than silently falling back to the defaults.

The FastCDC chunking parameters are not in this file — nothing here parses them. They are part of the repository's effective format identity, and the authoritative override is the chunking value on the commit-linked, content-addressed policy manifest, authored with tovio policy chunking — not replica-local config. Absence means the fixed format-1 defaults.

`config`¶

Your local preferences live in .tovio/config, one key = value per line. This is the file tovio config reads and writes:

tovio config get <key>
tovio config set <key> <value>
tovio config unset <key>
tovio config list

Notable keys:

Key	Meaning
`ui.celebration`	`on` (default) / `off` — the human-TTY celebration lines.
`ui.hints`	`on` (default) / `off` — the next-step hints.
`ui.ignore-advice`	`on` (default) / `off` — the `.tovioignore` suggestions described below.
`compat.git.notes`	`on` (default) / `off` — show the gentle one-line note on git-compat aliases.
`compat.git.aliases`	`on` (default) / `off` — enable the git-compat aliases entirely.

Preferences are advisory: a missing or unreadable file simply means "every default".

`.tovioignore`¶

A .tovioignore file at the repository root excludes paths from tracking. It uses gitignore syntax: one glob per line, # for comments, ! to negate, trailing / for directories.

# build artifacts
target/
node_modules/
*.log

# keep one tracked log
!important.log

Because TOVIO has no staging area, ignoring a path is how you keep it out of the auto-tracked working copy. An unparseable .tovioignore is a usage error (TVO-CLI-008, exit 2) naming the offending pattern.

What is excluded by default¶

Even with no .tovioignore, TOVIO keeps some paths out of the auto-tracked working copy:

Hidden entries — anything whose name starts with a dot (.git/, .idea/, .vscode/, .claude/, .env, …) and everything beneath a hidden directory, at any depth. The rule is by name, so it behaves identically on every platform.
Build/scratch dirs — target/ and node_modules/ at the repository root.

These are defaults, not permanent exclusions. If you want to track a hidden path anyway, re-include it with a ! negation in .tovioignore:

# track CI workflows and one hidden file — but nothing else hidden
!.github/
!.editorconfig

# keep the ignore file itself under version control, so it travels with the repo
!.tovioignore

A protective read policy also overrides the default: a hidden path a policy covers is tracked and sealed regardless. The exceptions are TOVIO's own metadata under .tovio/ (at any depth), any tovio-recovery-key.txt, and the generated checkout markers (*.tovio-unreadable, *.tovio-conflict, *.tovio-submodule) — those are hard exclusions that no negation or policy can re-include.

When TOVIO offers to write this file¶

TOVIO watches for well-known generated paths that the defaults above do not already cover — a __pycache__/, a Gradle build/, a nested packages/*/node_modules/ (the defaults are root-anchored, so only the top-level one is covered).

tovio init applies the unambiguous ones and tells you in one line. It never asks a second question.
tovio commit offers, once, on an interactive terminal. Decline and it never asks about that pattern again. With no terminal it just prints the lines to add and carries on.
tovio fsck lists everything it found; tovio fsck --fix-ignores applies the unambiguous ones.

An ambiguous name is only suggested with corroborating evidence — env/ needs a pyvenv.cfg inside it, build/ needs a CMakeCache.txt or a build.gradle beside it — and is written as an exact anchored path (/packages/web/dist/) so it can never affect a directory of the same name elsewhere. A path your history already tracks is left alone.

Turn it off entirely with tovio config set ui.ignore-advice off, or TOVIO_IGNORE_ADVICE=off.

This file is not a way to hide secrets¶

.tovioignore keeps a path out of TOVIO. It does not protect it: the file stays in plaintext on every machine that has a copy, and in your backups. If TOVIO spots a credential-shaped path it will say so and point you at a read policy instead of offering to ignore it:

tovio policy set 'config/production/**' --read 'clearance=secrets'

A protected path is committed encrypted and only identities with the clearance can read it. Policy beats ignore, always — once a path is protected, no ignore rule can suppress it.

Configuration¶

The .tovio/ directory¶

Object-store sharding¶

config.toml¶

config¶

.tovioignore¶