sow retain

Add, list, and remove explicit retained-Generation roots for local garbage collection.

Command

sow retain manages explicit local Generation roots. retain add can freeze only the current Built Generation; after later builds make it historical, its required package payloads remain protected.

Synopsis

sow retain add GENERATION [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]
sow retain ls             [-C|--workdir DIR] [-r|--repo NAME] [--json]
sow retain rm GENERATION  [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]

GENERATION must be a decimal integer greater than zero.

retain add

Requires GENERATION to equal the current Built Generation, verifies it, freezes its manifest under private Workspace state, and adds an explicit GC root. Older Generations cannot be recreated after the fact with retain add.

sow retain add 12 -r pgsql
retained generation 00000000000000000012: /srv/sow/.sow/pgsql/retained/00000000000000000012

The retained record protects payloads; it does not switch the current view or publish anything. Adding an already retained Generation is idempotent only when the verified record agrees with current evidence.

retain ls

Lists explicit retained records. It is read-only and therefore accepts neither lock options nor --dist.

sow retain ls -r pgsql
GENERATION	RECORD_IDENTITY	PATH
00000000000000000012	678beeae...	/srv/sow/.sow/pgsql/retained/00000000000000000012

An empty list is a successful result.

retain rm

Removes only the explicit retained root:

sow retain rm 12 -r pgsql
removed retained generation 00000000000000000012

It does not delete package bytes. Removing a Generation that is not retained is an idempotent no-op. A later local sow gc may reclaim payloads only if no other safety root reaches them.

Options

Flag	Commands	Meaning
`-C, --workdir DIR`	all	Workspace discovery start directory
`-r, --repo NAME`	all	Select a Repository
`-T, --timeout DUR`	`add`, `rm`	Maximum write-lock wait
`-N, --no-wait`	`add`, `rm`	Fail immediately when locked
`--json`	all	Emit the `sow.cli/v1` envelope

Exit behavior

Code	Trigger
`0`	Requested operation completed, including an empty list
`1`	Filesystem or runtime I/O failure
`2`	Invalid Generation syntax, discovery error, or implicit Repository selection is ambiguous
`4`	Write lock unavailable for `add` or `rm`
`5`	Generation manifest or Repository state is inconsistent
`6`	Explicit Repository is not configured, `retain add` does not name the current Built Generation, or another safety rule rejects the request