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.

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}.

See also

  • keryx media migrate — the usual source of reclaimable legacy objects.
  • Spec: docs/development/specs/0040-pluggable-object-stores.md