Retention

A retention rule keeps only the newest versions of the files under a directory. Older versions keep their commits and history, but Oak stops serving their content and reclaims the storage. It's for directories whose history you don't need byte for byte: build artifacts, exported datasets, rendered assets, large binaries that change often.

oak retention set build/artifacts --keep 3   # the newest 3 versions of each file
oak retention                                # list rules and what they've expired
oak retention remove build/artifacts

Retention is in preview. An admin turns it on per repository; until then the commands answer that retention isn't on for the repo.

What counts as a version#

A version is a distinct content of a file on main. Walking main from the newest commit back, the first N distinct contents of each path keep their bytes and older ones expire. A file reverted to an old content counts that content as new again, so it's kept.

The deepest matching rule wins: assets/ can keep 5 versions while assets/raw/ keeps 1. A rule for / covers the whole repository.

Commits on branches don't count as versions, but their content under a rule expires too once it's old and no longer in use, so editing a file 30 times on a branch doesn't keep 30 copies.

What is always kept#

• Everything an open branch or a release points at. The current tree of main, of every open branch, and of every tagged commit is complete. A closed branch's old content can expire like any other history.
• Content a file outside the rule uses. Oak stores content once per organization, so if the same bytes are also in a directory without a rule, they stay.
• Recent content. A version newer than 24 hours keeps its bytes even if it's past the limit.

What happens to an expired version#

• History is untouched. Commits, trees and hashes stay exactly as they were, so oak log, blame, and every hash check work as before. Only the bytes of the old version go.
• Clone and pull skip it. They report the versions they skipped (N historical file version(s) are no longer stored on the server), and checking out an old commit leaves those files out. oak clone --shallow never needs them.
• The web and raw API say so. Opening an expired version shows that it expired; GET /api/:owner/:name/raw/:commit/*path answers 410 Gone.
• Storage is reclaimed after 7 days. Until then, removing or loosening the rule brings the versions back. After that, the bytes are gone for good.

Older Oak CLIs can't skip expired versions, so a full clone or a pull that needs them fails with a message asking you to upgrade (or to clone --shallow).

Managing rules#

Organization owners and admins change rules, from the repository's Settings → Retention or the CLI. Every change is in the organization's audit log, with the rule before and after. Anyone who can read the repository can list the rules.

oak retention --json                        # rules, expired counts and bytes, can_edit
oak retention set / --keep 100 --repo acme/data

Rules take effect on the next retention run, which a change queues right away; repositories are also rechecked daily.

The same operations are on the HTTP API: GET, PUT ({"path", "keep_versions"}) and DELETE ?path= on /api/:owner/:name/retention.