managed on SOW

SOW v0.4.0

Mon, 24 Aug 2026 00:00:00 +0000

SOW 0.4.0 is an integrity and recovery release for Managed repositories. It makes the deep checker’s I/O contract explicit, prevents RPM trust from being assembled across unrelated keys, adds an audited way to correct mutable publication-target settings, and closes the remaining v0.3 migration and interrupted-publication gaps.

Plain repository behavior and the public pool/ + dists/ layout do not change.

Upgrade from 0.3

Migrate every v0.3 Repository explicitly

Stop all Workspace writers, back up the Workspace, install 0.4.0, and run sow repo migrate REPOSITORY once for each Repository before ordinary reads or writes. The migration is explicit and one-way; do not reopen a migrated database with SOW 0.3.

SOW v0.3.0

Mon, 10 Aug 2026 00:00:00 +0000

SOW 0.3.0 is a performance, durability, and product-focus release. Plain repository generation completes with one package-content pass. Managed repositories avoid per-object membership queries, reuse authenticated package facts, and promote payloads in bounded group commits. The shipping binary and its release pipeline are also consolidated around the repository workflows that SOW supports.

Plain: one package-content pass

The default unsigned sow create path hashes and parses each RPM or DEB once, with parallelism controlled by --jobs. Metadata is rendered from the retained inspection result. Before publication, SOW performs one final package-set and file-stat snapshot check, catching concurrent input changes without reading and hashing every package again.

SOW v0.2.0

Sat, 08 Aug 2026 00:00:00 +0000

SOW 0.2.0 is a self-contained RPM and DEB repository manager from Pigsty. Release artifacts target Linux and macOS as single Go executables.

Two operating modes

Plain mode indexes RPM and DEB files already present at one directory’s top level:

sow create /srv/repo

It writes repodata/, Packages, and Packages.gz in place. Plain mode has no Workspace, state database, generations, or DEB Release signing.

Design Records

Mon, 01 Jan 0001 00:00:00 +0000

Design records explain why SOW adopted a contract, what it rejected, and which evidence boundary applies. They are ordered by date, which records when the rationale first took its maintained form; lastmod records later editorial or implementation-alignment updates. Release notes and source tags remain authoritative for when behavior actually shipped.

Authority and evidence

This column is the maintained authority for design rationale and decision history. Current commands, configuration, and operator behavior remain in SOW Docs; exact behavior of a historical release remains attached to that release’s source tag and release note.

Design Principles

Sat, 08 Aug 2026 00:00:00 +0000

SOW is not primarily a metadata generator. It is an ownership and state-transition system whose output happens to be APT and RPM repositories. The following principles keep that system small enough to reason about.

One owner for every durable fact

Every durable fact has one scope and one authority:

Fact	Owner
Package bytes and package identity	Repository
Desired memberships and Built state	Repository
Generation and Changeset	Repository
Publication target binding and revisions	Repository + target storage/prefix
Publication attempt and applied checkpoint	Repository + target prefix
Remote inventory, grace, and delete evidence	Repository + target prefix

State is not silently shared across Repositories or publish prefixes. The same package may therefore exist once in each Repository or target. That is intentional: local deduplication must not create distributed ownership.

Build a YUM Repository

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial creates a new Managed RPM repository. You need a writable directory, and one or more RPM files.

1. Create the workspace

mkdir -p /srv/sow
cd /srv/sow
sow init .
sow repo new pigsty
sow dist new el9 --format rpm -r pigsty

The Dist name is an identifier chosen by you. SOW does not infer an operating-system release from el9.

Get Started

Mon, 01 Jan 0001 00:00:00 +0000

SOW builds static RPM/YUM and DEB/APT repositories; it is not an HTTP daemon. Choose one of two isolated paths:

Plain: sow create rebuilds indexes beside the packages in an ordinary directory.
Managed: a workspace tracks package membership, Dists, architecture views, policy, signing, generations, audit history, and publication targets.
Installation — Choose a release archive, RPM/DEB package, or source build; verify the installed binary.
Quick Start — Create and serve a flat repository from a directory of packages.

Build an APT Repository

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial creates a new Managed DEB repository. You need a writable directory, and one or more DEB files.

1. Create the workspace

mkdir -p /srv/sow
cd /srv/sow
sow init .
sow repo new pigsty
sow dist new trixie --format deb -r pigsty

The Dist name becomes the APT suite. It is an identifier chosen by you; SOW does not infer distribution semantics from trixie.

sow.yml Reference

Mon, 01 Jan 0001 00:00:00 +0000

sow.yml is the single configuration file of a managed workspace. It sits at the workspace root, declares which repositories and distributions exist, and holds the membership policy and signing settings that every build applies. Plain mode (sow create) never reads it.

This page lists every field the parser accepts. Anything not listed here is rejected — there are no undocumented keys and no keys reserved for future use.

How the file is read

SOW parses sow.yml with a strict decoder. Practically, that means:

sow init

Mon, 01 Jan 0001 00:00:00 +0000

sow init creates the root sow.yml and the private .sow/ state directory that make a directory a Workspace. It is also the convergence command for a config you wrote by hand: if sow.yml already declares Repositories and Dists, init materializes the ones that don’t exist yet and leaves the finished ones alone.

Synopsis

sow init [DIR] [--json]

DIR defaults to the current directory. init takes no -C/--workdir — the positional argument already names the target unambiguously.

Features

Mon, 01 Jan 0001 00:00:00 +0000

SOW has two isolated execution paths. Plain mode is a stateless rebuild of one directory; Managed mode records package membership and immutable repository generations in a workspace. Neither path silently adopts state from the other.

Capability matrix

Capability	Plain	Managed
RPM and DEB metadata	yes	yes
Mixed RPM + DEB operation	one directory	one Repository, separate Dists
Persistent membership and generations	no	yes
Per-architecture views and neutral packages	no	yes
`exclude` and version `limit` policy	no	yes
Metadata signing	no	RPM and DEB
RPM package signing	`--sign-with`	`never`, `fill`, `always`
Transaction journal and recovery	rerun `create`	workspace, Repository, publication
Queryable operation log and JSONL export	no	yes
Publication targets	no	filesystem and R2

SOW parses packages and renders metadata in-process. It does not invoke createrepo_c, dpkg-scanpackages, reprepro, or modifyrepo_c. RPM package signing is the exception: it needs the host rpm command and GPG environment because it rewrites package payloads.

Your First Workspace

Mon, 01 Jan 0001 00:00:00 +0000

Managed mode keeps configuration, membership, generations, and audit state. This example starts from an empty directory.

Initialize the workspace

sow init /srv/sow
cd /srv/sow

init creates:

/srv/sow/
├── sow.yml   # configuration; schema: sow/v3
└── .sow/     # SQLite state, locks, staging, recovery, journals

Do not edit or serve .sow/. init is idempotent: rerunning it validates and converges declared repositories and Dists; it does not reset a valid workspace.

Managed Workspaces

Mon, 01 Jan 0001 00:00:00 +0000

Managed mode is what you use when the same repository will be updated for months: packages arrive in batches, policy decides what stays, and you need to prove afterwards what changed and when. This page explains the three-tier model, the layout it produces, and how commands figure out which repository and which Dist you meant.

The three tiers

Workspace                          discovery and configuration boundary
└── Repository                     ownership boundary: pool, dists, SQLite, lock, generations
    └── Dist                       a named membership set in exactly one format
        └── Architecture View      a rendered projection — not a membership

Each tier has one job, and the boundaries are strict:

Core Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Plain or Managed

The two execution paths are separate.

	Plain	Managed
Entry point	`sow create DIR`	`init`, `repo`, `dist`, `add`, `rm`, `build`
State	package directory	`sow.yml` plus private SQLite/journals
Public layout	flat RPM/DEB indexes	Repository `pool/ + dists/`
Formats	RPM and DEB may share one directory	one format per Dist
Architecture views	no	yes
Policy and audit	no	yes
Metadata signing and publication targets	no	yes

Choose Plain when directory contents already equal the desired repository. Choose Managed when SOW must own membership, policy, generations, signing, audit, or publication.

sow repo

Mon, 01 Jan 0001 00:00:00 +0000

A Repository owns one pool/, one dists/, one SQLite database and one private state directory. It is the boundary of locking, transaction recovery, Generation numbering and Changesets — nothing is deduplicated across Repositories and no cross-Repository commit is atomic. sow repo manages that boundary.

Synopsis

sow repo ls [-C DIR] [--json]
sow repo new NAME [-C DIR] [-T DUR | -N] [--json]
sow repo show [NAME] [-C DIR] [-r NAME] [--json]
sow repo migrate [NAME] [--abort] [-j N] [-C DIR] [-r NAME] [-T DUR | -N] [--json]
sow repo rm NAME [-f|--force] [-C DIR] [-T DUR | -N] [--json]

Naming

A Repository name must match [a-z0-9][a-z0-9._-]* and may not be ., .., .sow, pool, dists, or collide with a Workspace reserved file.

Serve and Publish Repositories

Mon, 01 Jan 0001 00:00:00 +0000

SOW writes static files; it is not an HTTP server. This guide keeps the writable Workspace separate from the path Nginx serves.

Public and private paths

Mode	Public unit	Never serve
Plain	the directory passed to `sow create`	transient `.sow-plain-stage-*` output; no durable journal
Managed	one Repository’s complete `pool/ + dists/` tree	Workspace `sow.yml`, `.sow/`, SQLite, locks, journals, staging

For the workspace in First Workspace, the source Repository is /srv/sow/local. Do not make /srv/sow the document root.

Build the pigsty-infra Repository

Mon, 01 Jan 0001 00:00:00 +0000

pgsty/infra-pkg is the upstream build source for Pigsty Infra packages. This tutorial assumes the dual-architecture RPMs and DEBs already exist and covers the second half of the job: turning that pile of packages into a real, consumable, maintainable SOW repository named infra.

1. Put the packages under ~/repo

This tutorial uses the fixed path ~/repo throughout. Copy the existing packages into two input directories:

mkdir -p ~/repo/packages/rpm ~/repo/packages/deb
cp ~/pgsty/infra-pkg/dist/rpm/*.rpm ~/repo/packages/rpm/
cp ~/pgsty/infra-pkg/dist/deb/*.deb ~/repo/packages/deb/

Confirm that all four format-by-architecture cells contain real payloads:

sow dist

Mon, 01 Jan 0001 00:00:00 +0000

A Dist is a named set of packages in exactly one format (rpm or deb) inside one Repository. It is what a client points at. A Repository can hold RPM and DEB Dists side by side; they share one pool/ but render into completely separate dists/ subtrees.

Synopsis

sow dist ls [-C DIR] [-r NAME] [--json]
sow dist new NAME --format rpm|deb [-C DIR] [-r NAME] [-T DUR | -N] [--json]
sow dist show NAME [-C DIR] [-r NAME] [--json]
sow dist rm NAME [-f|--force] [-C DIR] [-r NAME] [-T DUR | -N] [--json]

Naming

Dist names follow the same rule as Repository names: [a-z0-9][a-z0-9._-]*, excluding ., .., .sow, pool and dists.

Membership Policy

Mon, 01 Jan 0001 00:00:00 +0000

Policy is the answer to “I dumped a build directory into this Dist and I do not want the debuginfo packages, and I only want the latest version of each package.” Two rules do that work, they run in a fixed order, and they run over the whole candidate set — not just the packages you happened to add this time.

The two rules and their order

candidate set  →  exclude  →  limit  →  Desired Membership

exclude drops packages that match a rule. limit then caps how many versions survive per package name and architecture. The order is fixed and never configurable, because the reverse order would let an excluded package consume a version slot on its way out.

sow add

Mon, 01 Jan 0001 00:00:00 +0000

sow add is the main write path. It parses the packages you point at, derives their format and architecture from the package headers, applies the Dist’s membership policy, and — unless you pass --skip — rebuilds every affected index before it returns. When the command exits 0, clients can already see the new packages.

Synopsis

sow add PATH... [-R|--recursive] [--skip] [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

Options

Flag	Description	Default
`-R, --recursive`	Descend into subdirectories of a `PATH` directory	off (top level only)
`--skip`	Update Desired state only; do not build	off
`-j, --jobs N`	Parallel workers for parsing, hashing and rendering	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a repository	selection rules
`-d, --dist NAME`	Select a distribution; repeatable	selection rules
`-T, --timeout DUR`	Maximum lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the versioned JSON envelope	false

Inputs and targets

PATH can be a file or a directory. A directory is scanned top level only unless you pass -R.

sow rm

Mon, 01 Jan 0001 00:00:00 +0000

sow rm takes packages out of the Desired Membership of the Dists you select and, by default, rebuilds the affected indexes immediately. It does not delete bytes from pool/ — membership and content are separate concepts, and reclamation is the separate conservative sow gc operation.

Synopsis

sow rm PACKAGE... [-c|--check] [--skip] [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

Options

Flag	Description	Default
`-c, --check`	Preview only; compute and print the plan without writing anything	off
`--skip`	Update Desired state only; do not build	off
`-j, --jobs N`	Parallel workers	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a repository	selection rules
`-d, --dist NAME`	Select a distribution; repeatable	selection rules
`-T, --timeout DUR`	Maximum lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the versioned JSON envelope	false

--check and --skip are mutually exclusive:

sow ls

Mon, 01 Jan 0001 00:00:00 +0000

sow ls is a read-only query over Package Objects and Dist Membership. It shows what each selected Dist should contain and whether that membership is present in the current Built Generation.

Synopsis

sow ls [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Select a Dist; repeatable	selection rules
`--json`	Emit the `sow.cli/v1` envelope	false

There is no --pool, --match, or output-format flag.

sow show

Mon, 01 Jan 0001 00:00:00 +0000

sow show resolves one package reference in the selected Repository and prints the complete Package Object. It is read-only and takes no write lock.

Synopsis

sow show PACKAGE [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Narrow candidates to these Dists; repeatable	Repository scope
`--json`	Wrap the result in the `sow.cli/v1` envelope	false

Package reference

PACKAGE accepts a sha256:<hex> content identity, canonical rpm:<NEVRA> or deb:<name>=<version>:<arch> coordinate, full package filename, or bare binary name. See Package References for the exact grammar.

sow where

Mon, 01 Jan 0001 00:00:00 +0000

sow where answers which Dists in the Workspace still carry one Package Object. It is read-only, searches every Repository by default, and takes no write lock.

Synopsis

sow where PACKAGE [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Restrict the search to one Repository	all Repositories
`-d, --dist NAME`	Restrict the search to named Dists; repeatable	all Dists
`--json`	Emit the `sow.cli/v1` envelope	false

Reference resolution

PACKAGE uses the same grammar as sow show: SHA-256 identity, canonical RPM/DEB coordinate, full filename, or bare name.

sow status

Mon, 01 Jan 0001 00:00:00 +0000

sow status is the cheap Repository health query. It reads state but does not hash files, verify signatures, recover Operations, build metadata, or take the write lock.

Synopsis

sow status [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Restrict status to these Dists; repeatable	all Dists
`--json`	Emit the `sow.cli/v1` envelope	false

Repository states

Every Repository tracks a Desired Revision in SQLite and the Built Generation represented by its public dists/ tree.

sow build

Mon, 01 Jan 0001 00:00:00 +0000

sow build is the explicit Desired-to-Built convergence command. It acquires the Repository write lock, recovers any decidable unfinished Operation, renders and verifies a complete Generation, then switches protocol pointers last.

Synopsis

sow build [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [-T|--timeout DUR | -N|--no-wait] [--json]

Flag	Meaning	Default
`-j, --jobs N`	Parallel workers; must be at least `1`	logical CPU count
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`-d, --dist NAME`	Build named Dists; repeatable	all affected Dists
`-T, --timeout DUR`	Maximum lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Wrap the result in the `sow.cli/v1` envelope	false

Without -d, SOW converges every affected Dist in the selected Repository. With -d, only those Dists converge; unselected changes remain dirty.