plain on SOW

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.

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.

sow create

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

sow create turns a directory that already contains .rpm and .deb files into a flat repository by writing indexes next to the packages. It is the whole of Plain mode: no sow.yml, no SQLite, no Workspace discovery. This page covers the one-pass scan contract, the --pigsty completion gate, and RPM signing with --sign-with.

Synopsis

sow create [DIR] [-j N] [--pigsty] [-S KEY [--overwrite]] [-T DUR | -N] [--json]

DIR defaults to the current directory.

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.

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 flat repository indexes beside them. Plain mode has no workspace, configuration file, database, desired state, or operation journal. The package directory is the authority; every index is a disposable projection of its current contents.

That distinction is intentional. Managed repositories retain state and recover transactions. Plain repositories are cheap to recreate: if a run fails or is interrupted, run the same command again and overwrite the derived metadata.

Quick Start

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

Plain mode builds a flat repository in one directory. It does not read sow.yml, create a workspace, or keep a database.

Prepare a directory

Put RPM and/or DEB files at the directory top level. sow create does not recurse and does not move or rename package files.

mkdir -p /srv/repo
cp /path/to/packages/*.rpm /path/to/packages/*.deb /srv/repo/

If one glob has no matches, copy the formats you actually have instead.

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.

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.