Operate a Local Repository

Roots tell Casita which graphs to keep. Routine operation is to inspect those roots, preview collection, and audit integrity before making changes.

Routine checks

$ casita --repository /var/lib/casita root ls
$ casita --repository /var/lib/casita gc --dry-run
$ casita --repository /var/lib/casita fsck --audit-only

gc --dry-run computes the collection plan without deleting data. fsck --audit-only checks physical payloads, logical records, and reachable closures without running the repair pass. It can report collectible residue or an unavailable format verifier without classifying the repository as corrupt. Read Errors and Integrity for the report categories.

Collect unreachable data

$ casita --repository /var/lib/casita gc

Collection removes unreachable records, then unreferenced payloads and chunks. Active mutations and retained readers pin the data they need while unrelated garbage remains collectible. The local profile can also try collection when a mutation starts on a filesystem at least 80% full. It may then release roots explicitly marked evictable, preserving permanent roots and data held by active operations. Explicit capacity monitoring and collection remain useful because busy work can defer that attempt.

Back up and restore

Back up the repository directory as one unit:

1. Stop or quiesce every process that can write, retain, or collect.
2. Copy the complete directory, including casita.sqlite and blobs.
3. Restore that complete copy, then open it and run fsck before relying on it.

Ordinary file copy tools do not participate in Casita’s locks. A live file-by-file copy may combine incompatible state and payload revisions. Treat the restored copy as a separate repository; its revision tokens cannot order changes against the original.

Respond to a failed integrity check

Preserve the affected repository before attempting recovery. A normal fsck may rebuild a corrupt Bao outboard from verified local bytes. With an independently verified local replica, --source can replace a missing or corrupt physical representation:

$ casita --repository /var/lib/casita fsck --dry-run
$ casita --repository /var/lib/casita fsck --source /srv/casita-replica

--dry-run previews physical repair actions without writing. Repair never invents object records or changes roots. For reachable missing or invalid content that cannot be repaired from a trusted replica, restore a coherent backup or re-import and re-sync. For collectible residue, run gc and audit again. For an Unchecked namespace, use a build with its format verifier.

Read Local Repository for layout and Garbage Collection for collection order.