CLI Commands on SOW

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.

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.

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.

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.

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

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:

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.

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: