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

Coordinated Publication Decision

Fri, 14 Aug 2026 00:00:00 +0000

Decision finalized for SOW 0.4.0

An earlier version of this record proposed an rclone executor, publish --dry-run, and a separate sow audit command. None of those surfaces shipped in 0.4.0. SOW has no rclone dependency, publish has no --dry-run, and sow audit is not a command.

This page preserves the decision boundary so a historical proposal cannot be mistaken for the current product. The normative behavior is documented in sow publish and Publication & Recovery.

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.

Publication & Recovery

Sat, 08 Aug 2026 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.

Tutorials

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

Each tutorial starts from a new workspace. Commands are intended to be run in order; replace uppercase placeholders and package paths for your environment.

If you have not installed SOW yet, start with Installation and Quick Start. The tutorials below cover the managed repository path.

Build a YUM Repository

A managed RPM repository with per-architecture views, noarch projection, debuginfo filtering, version limits, and a working dnf client configuration.

Build an APT Repository

A managed DEB repository with a Debian-style pool, by-hash indexes, and a deb822 client configuration.

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 changes

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

sow changes compares Built Generations. It reports physical Repository-relative file changes; it does not show unbuilt Desired changes and is not a remote transaction protocol.

Synopsis

sow changes [BASE_GENERATION] [-C|--workdir DIR] [-r|--repo NAME] [--json]

Flag	Meaning	Default
`-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 is Repository-wide and rejects -d/--dist.

sow publish

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

sow publish delivers one Repository’s current Built Generation to a named target from the targets: map in sow.yml. The target binds its Repository and provider; the command does not accept --repo or --dist.

Synopsis

sow publish TARGET [--abort | --rebind] [-C|--workdir DIR] [-T|--timeout DUR | -N|--no-wait] [--json]

Flag	Meaning	Default
`--abort`	Abandon a reconciled attempt that has not reached durable commit intent	false
`--rebind`	Confirm and record permitted target name/public endpoint/cache-TTL changes	false
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-T, --timeout DUR`	Maximum Repository-lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the `sow.cli/v1` envelope	false

TARGET must name a configured filesystem or r2 publication target. --abort and --rebind are mutually exclusive.

sow gc

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

sow gc has two deliberately separate modes. With no positional target it collects unreachable local pool payloads. With TARGET it maintains one configured publication target.

Synopsis

sow gc          [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]
sow gc TARGET   [-C|--workdir DIR]                  [-T|--timeout DUR | -N|--no-wait] [--json]

Flag	Meaning	Default
`-C, --workdir DIR`	Workspace discovery start directory	current directory
`-r, --repo NAME`	Select a Repository for local GC only	selection rules
`-T, --timeout DUR`	Maximum Repository-lock wait; `0` waits indefinitely	`0`
`-N, --no-wait`	Fail immediately when the lock is held	false
`--json`	Emit the `sow.cli/v1` envelope	false

gc TARGET -r NAME is a usage error because the target already binds a Repository. --dist is not accepted in either mode.