SOW: Package Repository Manager by Pigsty on SOW

SOW 0.2: Documentation Preview

Tue, 04 Aug 2026 00:00:00 +0000

Published: 2026-08-04 · Version: sow 0.2.0-dev

SOW is a self-contained package repository manager from Pigsty. It is one static Go binary that creates and maintains APT (DEB) and YUM (RPM) repositories on Linux and macOS, and it does the whole job itself: createrepo_c, dpkg-scanpackages, reprepro, and modifyrepo_c are never invoked. There is no daemon, no database server, and nothing to install alongside it. The name is the verb — you sow packages into a repository, and the repository grows.

Download & Install

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

SOW is one static executable. There is no installer, no package to add, no service to enable, and no state directory until you run a command that needs one. Installing it means putting a single file on your PATH.

Prebuilt binaries

Release archives for every supported platform are published on the GitHub releases page. Download the archive that matches your OS and CPU, extract it, and move the binary into place:

Build a YUM Repository

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

This tutorial builds a production-shaped RPM repository from scratch. By the end you will have a workspace holding a pigsty repository with an el9 Dist, two architecture views rendered from one package pool, debuginfo noise filtered out, only the newest version of each package kept, and a .repo file that dnf accepts.

Plan for about fifteen minutes. Every command runs locally; nothing talks to the network.

Before you start

You need three things.

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.

Install SOW

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

SOW ships as a single static executable. Installing it means putting one file somewhere on your PATH. There is no package to install, no service to enable, and no state directory created until you run a command that needs one.

Supported platforms

The binary is built with CGO_ENABLED=0, so it has no libc dependency and runs on any reasonably modern kernel of the matching OS and CPU family.

OS	`amd64`	`arm64`
Linux	supported	supported
macOS (Darwin)	supported	supported

Windows is not supported. SOW relies on POSIX advisory locks, hardlinks, and atomic rename, and it is only tested on local POSIX filesystems — network filesystems such as NFS do not provide the locking and durability semantics it depends on.

Design Principles

Mon, 01 Jan 0001 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 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 scan rules, the atomic --pigsty compatibility operation, 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.

Build an APT Repository

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

This tutorial builds a managed APT repository: a Debian-style package pool grouped by source package, one index per architecture, by-hash index copies so clients never race a rebuild, and client configuration in both the modern deb822 format and the legacy one-liner.

Plan for about fifteen minutes.

Before you start

You need SOW installed (Installation), some .deb files, and a directory you can write to.

This tutorial continues from Build a YUM Repository by adding a second Dist to the same pigsty repository — one pool, two package ecosystems. If you are starting fresh, run these three commands first and then continue from Step 1:

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:

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.

Quick Start

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

This page takes about five minutes. You will put some packages in a directory, run one command, serve the directory over HTTP, and install from it with dnf or apt. No configuration file, no workspace, no database — plain mode writes indexes next to your packages and nothing else.

1. Collect the packages

Any directory containing .rpm or .deb files works. The files stay where they are; SOW never moves or renames them.

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.

System Model

Mon, 01 Jan 0001 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.

Your First Workspace

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

This page takes about ten minutes and builds a managed repository from nothing: a workspace, one repository, an RPM distribution and a DEB distribution inside it, packages added to both, and a look at what landed on disk. Unlike plain mode, a workspace remembers what you asked for — so you add and remove packages by name instead of by shuffling files around, and SOW rebuilds only what changed.

1. Create the workspace

mkdir -p /srv/sow
cd /srv/sow
sow init .

initialized /srv/sow: config_created=true repositories_initialized=0 dists_initialized=0

init created two things: sow.yml, which is the single source of truth for what this workspace contains, and a hidden .sow/ directory holding locks, per-repository SQLite state, and the operation journal used for crash recovery. You never edit anything under .sow/ and you never serve it.

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:

Package References

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

sow rm, sow show, and sow where all take a PACKAGE argument. This page defines what you may write there. The same grammar applies to all three commands; only the handling of an ambiguous name differs.

Nothing here applies to sow add, which takes filesystem paths, not references.

The five forms

Form	Example	Matches
Content digest	`sha256:d06d7f23b9cf...b98b1229`	Exactly one package object
RPM coordinate	`rpm:pev2-0:1.23.0-1.noarch`	Exactly one RPM
DEB coordinate	`deb:libpq5=18.3-1.pgdg12+1:amd64`	Exactly one DEB
Filename	`pev2-1.23.0-1.noarch.rpm`	The package stored under that filename
Bare name	`pev2`	Every version and architecture of that name

The first three are exact: they name one object and either hit it or fail. The last two are conveniences that may match more than one object.

Sign Your Repository

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

An unsigned repository is a repository anyone on the path can rewrite. This tutorial closes that hole: you generate a signing key, configure SOW to sign what it publishes, verify the signatures by hand, and turn on client-side enforcement so dnf and apt refuse anything that does not check out.

Plan for about twenty minutes.

Two independent trust chains

Package repositories have two things worth signing, and they are not the same thing.

Single-Payload Repository

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

The 0.3 development design changes the physical RPM layout while preserving the ownership model introduced in v0.2. Its objective is precise: within one Repository and within each publish prefix, every live Package Object has exactly one payload path.

Development design

This page describes the implemented 0.3 source layout. The released v0.2 operational reference still describes C2 view-local hardlinks. Read Design Evolution before migrating an existing v0.2 repository.

Canonical tree

<repo>/
├── pool/ # canonical package payloads
│ └── <prefix>/<source>/<filename>
└── dists/ # metadata-only projections
 ├── <rpm-dist>/<arch>/repodata/
 └── <deb-dist>/<component>/binary-<arch>/

There is no canonical release/, reposync/, per-view pool/, per-generation package tree, or snapshot package tree. pool/ + dists/ is the complete relocation and publication unit.

sow config

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

sow config has two read-only subcommands. config check is the full preflight over sow.yml — run it after every hand edit and in CI. config show prints the configuration SOW actually computed, which is where you confirm that defaults, inherited architectures and normalized aliases resolved the way you expected.

Neither subcommand creates directories, touches a database, or corrects your file.

Synopsis

sow config check [-C DIR] [--json]
sow config show [--all] [-C DIR] [-r NAME] [-d NAME]... [--json]

sow help config lists both.

Core Concepts

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

Once you have run the quick start and built a workspace, a handful of ideas explain everything else SOW does. This page covers them: the two modes and how to choose, the four layers of the managed model, and the distinction between what you asked for and what is currently published.

Two ways to build a repository

SOW has two engines that never touch each other. Plain mode does not read sow.yml, does not perform workspace discovery, and does not create a database. Managed mode never treats a plain directory as a repository. Picking one is the first decision you make.

Repository Layout

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

SOW’s on-disk layout is fixed. There is no path: setting, no template, and no way to relocate a repository — every path is derived from the workspace root, a validated name, and a constant relative segment. This page is the complete map, so you know what to serve, what to copy, and what to keep private.

Plain mode

sow create writes indexes next to the packages and touches nothing else. The directory you point it at stays a flat repository: packages and metadata share one level.

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.

Publication & Recovery

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

Building and publishing are separate state transitions. A build produces a target-neutral Generation. Publication applies that Generation to one provider prefix and records enough evidence to recover without guessing.

Ownership split

Repository-scoped	Target-prefix-scoped
Package Object	Publication Attempt
Desired and Built state	Applied Checkpoint
Generation and Changeset	Remote inventory
Retained payload/metadata references	Grace and deletion evidence

The split prevents a successful filesystem publication from being treated as proof about R2, and prevents one target’s partial attempt from contaminating another target.

Serve Repositories

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

SOW builds a static directory. Anything that can serve static files can serve it — there is no daemon, no application server, and no runtime component. This tutorial covers what to point a web server at, a tested Nginx configuration, a one-command local preview, and how to move the tree to a host that cannot reach your build machine.

Plan for about fifteen minutes.

What you actually serve

For a managed workspace, the document root is the repository directory:

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 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.

Compatibility Boundaries

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

“Compatible” is too broad to be a useful engineering claim. A package may install while a mirror tool refuses the same metadata; a tree may work on POSIX disk while multiplying objects after upload. SOW therefore treats compatibility as a set of independent gates.

The layers

Layer	Question	Required evidence
Format	Is the metadata valid rpm-md / Debian archive syntax?	parser and structural validation
Ordinary client	Can `apt`, `dnf`, or `yum` refresh, resolve, download, verify, and install?	real client run
Mirror tool	Can the named mirror tool materialize the repository safely?	that exact tool and version
Relocation	Does a whole-root copy remain byte-closed and consumable?	copy + manifest + client run
HTTP/proxy	Are relative URLs normalized inside the same prefix without traversal or double encoding?	target HTTP matrix
Storage	Do object identity, conditional operations, listing, caching, and deletion match the state machine?	real provider protocol test

No row inherits PASS from another row or from an earlier Repository layout.

Exit Codes

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

Every sow command exits with one of seven codes. They are stable, they are the same for every command, and they are meant to be branched on in scripts — the distinction between “this failed” and “this was correctly refused” is the whole point of having more than one nonzero code.

Code	Meaning
`0`	Complete success, or an idempotent no-op
`1`	Runtime I/O, parser, renderer, or unknown internal error
`2`	Usage, workspace discovery, or configuration error
`3`	Partial success: at least one item committed, at least one failed
`4`	Write lock unavailable — held and `--no-wait`, or the timeout expired
`5`	Integrity or recovery error, or `check` judged the result not deliverable
`6`	Expected rejection: conflict, protected, no match, incompatible architecture

Human-readable results go to stdout; warnings and diagnostics go to stderr. Each code has a stable message prefix on stderr, and a matching class in JSON output:

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.

Migrate from createrepo_c / reprepro

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

You already have a repository. This tutorial replaces the tool that builds it without breaking the clients that consume it — including the leftover files nobody warns you about and the layout differences you should know before, not after.

Two paths, depending on what you have. Read the one that matches, then the comparison at the end.

Choose your target

You have	Migrate to	Read
`createrepo_c` on a directory of RPMs	Plain mode, in place	Path A
`dpkg-scanpackages` on a flat DEB directory	Plain mode, in place	Path A
A reprepro archive with `pool/` and `dists/`	Managed workspace	Path B
`createrepo_c` plus scripts for multiple architectures	Managed workspace	Path B

Plain mode is the drop-in replacement: same directory, same URLs, one command instead of a toolchain. Managed mode is a change of shape — a workspace, a pool, per-architecture views — and gives you membership policy, transactional builds, and an audit trail. Migrate to Plain first if you just want the dependency gone; move to Managed when the repository’s lifecycle is what hurts.

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.

Design Evolution

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

SOW’s old documents came from three materially different systems. Preserving them without a version boundary made contradictory statements look simultaneous. This page keeps the useful decisions while making their scope explicit.

Timeline

Line	Primary problem	Physical model	Disposition
V1 experiment (July 2026)	absorb Pigsty’s existing APT/YUM trees and remote publishing workflow	Git/CAS, route-aware projections, edge/provider contracts	archived research and implementation evidence
v0.2.0	ship a compact local Plain + Managed repository manager	root Pool plus C2 view-local RPM hardlinks	released; operational docs remain live
0.3 development	publish one canonical payload per Repository/target prefix	root Pool plus metadata-only views and target-scoped publication	implemented in source; release evidence pending

What survived V1

The broad V1 program explored repository adoption, remote publication, provider fencing, edge authorization, migration, recovery, and large-repository evidence. Much of its exact Git/CAS/route model was replaced, but several principles survived:

JSON Output

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

Every command that produces data accepts --json. The output is a single line on stdout carrying a versioned envelope, so you can pipe it straight into jq without worrying about which command produced it.

sow status --json

{"schema":"sow.cli/v1","command":"status","ok":true,"repository":"pigsty","operation":null,
 "result":{"repository":"pigsty","status":"clean","ready_to_copy":true,"desired_revision":4,
 "built_generation":4,"dirty_dists":[],"dirty_reasons":[],"pending":{"count":0,"bytes":0},
 "recent_operation":{"id":"8632724976452398569","kind":"add","state":"done",
 "created_at":"2026-08-04T04:07:17.665377Z","updated_at":"2026-08-04T04:07:18.293848Z"},
 "repository_locked":false},"errors":[]}

(Line-wrapped here for readability; the real output is one line.)

The envelope

Field	Type	Meaning
`schema`	string	Always `sow.cli/v1`. Check it before parsing anything else.
`command`	string	The command as invoked, including the subcommand: `add`, `repo ls`, `config show`.
`ok`	bool	`true` when `errors` is empty. Equivalent to exit code `0`.
`repository`	string or null	The selected repository, or `null` for workspace-wide and plain-mode commands.
`operation`	string or null	The operation ID for write commands, `null` for read-only ones.
`result`	object or null	Command-specific payload, described below.
`errors`	array	Zero or more `{code, class, message}` objects.

All seven fields are always present. result is null only when the command failed before it could produce anything — an unknown flag, for example.

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.

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.

Compatibility

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

SOW writes standard rpm-md and Debian archive metadata, so the question is not whether a client can read it but which clients have actually been verified against it. This page lists the tested matrix, the platforms the binary runs on, and the handful of constraints that will bite you if you ignore them.

Package manager clients

Every row below was exercised end to end against a repository built by SOW: refresh the index, list packages, and install one.

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 never deletes bytes from pool/ — membership and content are separate concepts, and there is no garbage collection.

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:

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.

sow ls / show / where

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

Three commands answer three different questions. ls lists what a Dist should contain, show inspects one package object in detail, and where finds which Dists — in any Repository — carry a package. All three are read-only, take no write lock, and share the same --json envelope.

Synopsis

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

Common options

Flag	Description	Default
`-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
`--json`	Emit the versioned JSON envelope	false

There is no --pool, no --match, and no per-command format flag.

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.

sow build / status / check / changes

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

One concept, one command. status is the cheap read, check is the full verification, build is the only thing that changes the public tree, and changes is the physical file diff between Generations. This page covers all four, because you almost always use them together.

Synopsis

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

The state model

Every Repository tracks two things: the Desired Revision in SQLite, and the Built Generation that the dists/ tree on disk corresponds to.

sow log

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

Every write command inside a Repository commits an application-level Operation to that Repository’s SQLite database before it produces any external file side effect. That record is what makes crash recovery possible — and once the Operation reaches a terminal state, the same record is your audit trail. sow log reads it.

Synopsis

sow log [OPERATION] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME] [--json]
sow log export [FILE] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]
sow log prune BEFORE [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]

Operation lifecycle

Understanding the state field is most of understanding the log:

Page Not Found

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

The page you are looking for has moved, been deleted, or does not exist.

Try the documentation home, or search with ⌘K / Ctrl K.