Features on SOW

Capability Overview

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

SOW is a self-contained software repository manager: a single static Go binary (CGO_ENABLED=0) that creates and maintains APT (DEB) and YUM (RPM) repositories on Linux and macOS. It does not call createrepo_c, dpkg-scanpackages, reprepro, or modifyrepo_c, and it does not run a daemon. This page is the map of what it covers; the rest of this section explains how each piece works.

The current release is sow 0.2.0-dev.

Two execution paths

SOW gives you two ways to build a repository, and they are deliberately isolated from each other. Nothing is shared between them except the low-level package parsers, renderers, version comparators, locks, and safe file primitives.

Plain Flat Repositories

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

sow create takes a directory that already contains .rpm and .deb files and writes an index over them, in place. That is the whole job. This page explains what it reads, what it writes, what it promises never to touch, and how it survives being killed halfway through.

The invariants

Three rules hold for every sow create run, and everything else follows from them:

SOW only replaces index paths it owns. Your packages, your README, your leftover files from another tool — untouched. The one exception is --pigsty, which is an explicit request to delete specific packages.
Same input, same bytes. Timestamps and compression parameters are fixed and sort order is stable, so re-running over an unchanged directory produces a byte-identical index and reports noop=true.
The commit is all-or-nothing per format pointer. Metadata is fully generated and validated in a staging area on the same filesystem, and only then swapped in with atomic renames. If anything fails before the swap, the previous index keeps serving.

Plain mode has no workspace, no configuration file, and no database. It does not read sow.yml even if one exists in a parent directory, and it never performs workspace discovery.

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:

Pool & Architecture Views

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

If you list a Managed repository you will find the same package file at three different paths, and du will insist it only occupies space once. That is not an illusion and it is not a symlink. This page explains the projection model — why it exists, what it guarantees, and the one constraint it puts on your filesystem.

The invariant

The root pool owns the bytes. Everything under dists/ is a projection that can be deleted and rebuilt without touching an owned object.

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.

Signing Model

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

There are two different questions a client can ask about a repository, and SOW answers them with two separate mechanisms. Confusing them is the most common source of “I signed it but dnf still complains”, so this page starts by pulling them apart.

Two independent trust chains

	Metadata signing	RPM package signing
Question answered	“Is this index really from you, and unmodified?”	“Is this `.rpm` file really from you?”
Configured by	`signing.rpm.metadata`, `signing.deb.metadata`	`signing.rpm.packages`
Produces	`repodata/repomd.xml.asc`, `InRelease`, `Release.gpg`	an OpenPGP signature embedded in the package
Changes package bytes	no	yes
Client setting	dnf `repo_gpgcheck=1`, apt `Signed-By`	dnf `gpgcheck=1`
Available in Plain mode	no	yes, via `create -S KEY`

They are configured separately and can be used separately. Metadata signing alone is usually the right starting point: it authenticates the whole index in one place and requires no change to the packages you received from upstream.

Transactions & Recovery

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

Repository tools fail in one of two embarrassing ways: they leave an index that points at packages that no longer exist, or they corrupt their own database and require a rebuild from scratch. SOW is built to make both impossible, and this page explains the machinery that does it.

The invariant

A client following a protocol pointer always reads a complete old view or a complete new view. There is no third option, including after a power loss.

Observability & Audit

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

Four read-only commands answer four different questions, and each one refuses to do the others’ job. That separation is deliberate: a cheap status check that occasionally hashes the whole repository is useless in a loop, and a full verification that silently repairs things is useless as evidence.

Command	Question	Cost	Writes
`status`	What state is this repository in right now?	cheap, no hashing	never
`check`	Can I prove this tree is correct and shippable?	full verification	never
`changes`	Which files do I need to copy to bring a mirror up to date?	reads the generation manifest	never
`log`	What happened, when, and to which packages?	reads the ledger	`prune` only

`status` — cheap state

$ sow status
repository=pigsty status=clean ready_to_copy=true revision=4 generation=4 dirty_dists= pending=0/0 locked=false

status never hashes the repository, never recovers an operation, and never builds. It reports the repository state, the Desired revision, the Built generation, which Dists are dirty, how many pending payload objects exist and how many bytes they occupy, whether a lock is held, and the most recent operation.

Features on SOW

Capability Overview

Two execution paths

Plain Flat Repositories

The invariants

Managed Workspaces

The three tiers

Pool & Architecture Views

The invariant

Membership Policy

The two rules and their order

Signing Model

Two independent trust chains

Transactions & Recovery

The invariant

Observability & Audit

status — cheap state

`status` — cheap state