dist on SOW

System Model

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

The model is deliberately layered. Configuration expresses intent, the database records owned state, and the public tree is a deterministic projection. None of those layers may quietly become a substitute for another.

Object hierarchy

Workspace
├── Repository
│   ├── Package Object
│   ├── Dist
│   │   └── Membership -> Package Object
│   ├── Desired state
│   ├── Built Generation
│   └── Retained Generation references
└── Publication Target
    └── Repository + provider + prefix

Workspace

A Workspace supplies discovery, configuration, and coordination. It owns sow.yml, the private .sow/ directory, and stable lock paths. It is not a package deduplication domain.

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.

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.

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.

Repository Layout

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

SOW has one fixed Managed layout: package payloads live once under pool/, while dists/ contains metadata-only client views. The complete repository directory is the unit to serve, copy, or publish.

Plain mode

sow create writes indexes next to existing packages and leaves every unrelated file unchanged:

/srv/offline/
├── blackbox_exporter-0.28.0-1.x86_64.rpm
├── libpq5_18.3-1.pgdg12+1_amd64.deb
├── repodata/
│   ├── <sha256>-primary.xml.gz
│   ├── <sha256>-filelists.xml.gz
│   ├── <sha256>-other.xml.gz
│   └── repomd.xml
├── Packages
├── Packages.gz
└── repo_complete                         # only with --pigsty

Flat RPM metadata uses a bare package basename; flat DEB metadata uses ./<filename>. While a build is active, .sow-plain-stage-* contains private generated output. Plain has no durable journal or recovery state; a later create discards stale reserved temporary paths and rebuilds. Never serve or copy those temporary paths.

Pool & Metadata Views

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

The invariant

Within one Repository, every live Package Object has one canonical payload path under pool/. Dists and architecture views own metadata, not aliases of package bytes:

<repo>/pool/...                              canonical package payloads
<repo>/dists/<rpm-dist>/<arch>/repodata/... RPM metadata only
<repo>/dists/<deb-dist>/main/binary-*/...   APT metadata only

The same digest in another Repository or publication prefix is a separately owned object. SOW deliberately does not turn local deduplication into shared distributed ownership.

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.

sow export

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

SOW provides one export subcommand: sow export rpm-leaf. It creates an external, standalone RPM repository whose repodata uses local pool/... hrefs.

Synopsis

sow export rpm-leaf DIST ARCH DIR [--hardlink] [-C|--workdir DIR] [-r|--repo NAME] [--json]

Argument	Requirement
`DIST`	Canonical configured RPM Dist name
`ARCH`	`x86_64` or `aarch64`
`DIR`	Absent or empty destination outside Repository, private-state, and filesystem-target roots

Flag	Meaning	Default
`--hardlink`	Use hard links for trusted, same-filesystem, read-only output	copy files
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository	selection rules
`--json`	Emit the `sow.cli/v1` envelope	false

The command accepts no --dist, jobs, timeout, or lock option.