nordisk/holger

Retention / GC planner — the beginner's guide

The problem, in one sentence

A package repository fills up: every build pushes a new version, old ones pile up forever, and one day the disk is full of serde 1.0.1 through 1.0.219 that nobody will ever download again.

What retention does

Retention is a rule for what to keep. The most common one: "keep the last 5 versions of each package, throw away the rest." Others: "throw away anything older than 90 days" or "keep the newest until the repo is under 50 GB."

Holger's planner takes your rule and your repository and tells you exactly which artifacts it would keep and which it would throw away — without touching anything. It's a preview, like "empty trash" showing you the list first.

Try it

holger-server retention --config holger.ron --repo rust-prod --keep-last-n 5

You get back something like:

  rust-prod: 812 names, keep 4060 / reclaim 15380 — kept 9.9 GiB, reclaimable 41.2 GiB

Read that as: "across 812 package names, I'd keep 4060 artifacts (9.9 GB) and could free up 41.2 GB by removing 15380 old versions." Add --verbose to see each one.

The safety net

By default the planner never throws away the newest version of a package — even a strict age or size rule can't empty a package to nothing. That's the protect_latest_per_name guard; you'd have to pass --no-protect-latest to turn it off.

Previewing vs actually deleting

By default the tool only shows you the plan — it deletes nothing. That's the safe preview. When you're sure, add --execute and it actually reclaims the old versions:

holger-server retention --config holger.ron --repo rust-prod --keep-last-n 5            # preview
holger-server retention --config holger.ron --repo rust-prod --keep-last-n 5 --execute  # do it

Two safety nets when it deletes for real: it checks each file's fingerprint right before removing it (so it can never delete the wrong bytes), and it will never touch the newest/protected version of a package. Every reclaim is written to the audit log so there's always a record of what was cleaned up.

(Note: this per-file reclaim works on the writable, loose-file repos. Dropping a whole sealed immutable archive box at once is a separate, still-planned job.)

The words you'll see

• keep-last-N — keep the N newest versions of each name.
• max-age — throw away things older than X.
• quota — keep the newest until the repo fits in X bytes.
• reason — why each artifact was kept or reclaimed (superseded-by-newer, aged-out, quota-evicted, protected-latest, …).