Skip to content

keryx media gc

Description

Reclaim object-store blobs that no workspace references — the deliberate counterpart to keryx never deleting during normal operation (R-STO-6).

Re-rolled takes, media removed from a board, and pre-0040 path-keyed objects (left behind by media migrate) accumulate by design. media gc is the opt-in way to clear them.

Safety

Two properties make it safe to run:

  • It sweeps the whole reel root, never one workspace. Blobs are content-addressed and therefore shared across reels (identical content is stored once), so a narrower view could delete a blob another reel still needs.

  • The version ledger counts as a reference. Both media.lock (current pins) and media.log (every historical version) are scanned, so media rollback targets are never collected.

  • A manifest it cannot account for stops a prune. Every object kind keryx stores knows how to enumerate its own directories. If the scan finds a media.lock in a directory no kind claims, then something references blobs the sweep did not see — and pruning against that incomplete picture would delete live data. So it refuses, names the directory, and deletes nothing.

The realistic way to hit this is a project that sets workspace.root: gc honours it, and the --workspace commands do not, so the two can end up looking at different roots.

A report is never refused — only a prune. Otherwise attempting the destructive thing would be the only way to discover the problem.

It also reports by default — nothing is deleted without --prune.

Usage

keryx media gc [--prune]
--prune Actually delete the orphans. Without it, gc only reports.

Run keryx media gc --help for the authoritative, always-current flag set.

Output

media gc: 2 referenced, 1 orphan(s)
  - blog/blobs/zz/zzorphan
Nothing deleted. Re-run with --prune to reclaim them.

With --output json, the envelope carries {referenced, orphans, orphan_bytes, deleted, pruned, sample_orphan}, plus unclaimed when a prune was refused — the directories carrying a manifest no kind claimed.

A refused prune exits non-zero and names the first offending directory:

media gc: 1 found, starting at other-root/demo — nothing was deleted

See also