Command on SOW

sow create

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

sow create 把一个已经放着 .rpm / .deb 的目录变成平面仓库（flat repository）：在包旁边写出索引文件。它就是 Plain 平面模式的全部——没有 sow.yml、没有 SQLite、不做工作区发现。本页讲清单遍扫描契约、--pigsty 完成门禁，以及 --sign-with 的 RPM 包签名。

sow init

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

sow init 创建根级 sow.yml 与私有状态目录 .sow/，这两样东西让一个目录成为工作区（Workspace）。它同时也是手写配置的收敛命令：如果 sow.yml 里已经声明了 Repository 与 Dist，init 会把还不存在的那些实体化出来，已完成的原样跳过。

sow config

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

sow config 有两个只读子命令。config check 是对 sow.yml 的全量预检——每次手工改完配置以及在 CI 里都该跑一遍。config show 打印 SOW 实际算出来的配置，用它确认默认值、继承的架构与规范化别名是不是按你预期解析的。

sow repo

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

一个仓库（Repository）独占一份 pool/、一份 dists/、一个 SQLite 数据库与一个私有状态目录。它是锁、事务恢复、Generation 编号与 Changeset 的边界——跨仓库不去重，也不承诺跨仓库原子提交。 sow repo 管理的就是这条边界。

命令

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

每条顶层命令单独成页；config、repo、dist、retain、 export、log 等命令组在同一页说明其子命令。

二进制内置的 sow help 是语法权威。本手册在此基础上补充选择规则、状态变化、输出契约、失败行为与可直接使用的示例。

sow dist

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

Dist 是一个仓库内、单一格式（rpm 或 deb）的具名包集合。客户端指向的就是它。一个仓库可以同时拥有 RPM Dist 与 DEB Dist，两者共用一份 pool/，但渲染进完全独立的 dists/ 子树。

sow add

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

sow add 是主要的写入路径。它解析你指定的包，从包头推导格式与架构，执行 Dist 的成员策略，并且—— 除非你加 --skip——在返回前重建全部受影响的索引。命令退出码为 0 时，客户端已经能看到新包了。

sow rm

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

sow rm 把包从你选定的 Dist 的期望成员集中拿掉，并默认立即重建受影响的索引。它不会从 pool/ 删除字节——成员关系与内容是两个概念,回收由独立的保守操作 sow gc 完成。

sow ls

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

sow ls 是针对 Package Object 与 Dist Membership 的只读查询。它显示所选 Dist 应包含哪些包，以及这些成员是否已经进入当前 Built Generation。

语法

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

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`-d, --dist NAME`	选择 Dist；可重复	选择规则
`--json`	输出 `sow.cli/v1` Envelope	false

该命令没有 --pool、--match 或输出格式参数。

sow show

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

sow show 在所选 Repository 中解析一个包引用，并打印完整 Package Object。该命令只读，不获取写锁。

语法

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

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`-d, --dist NAME`	将候选项收窄到指定 Dist；可重复	整个 Repository
`--json`	将结果包装进 `sow.cli/v1` Envelope	false

包引用

PACKAGE 可使用 sha256:<hex> 内容身份、规范的 rpm:<NEVRA> 或 deb:<name>=<version>:<arch> 坐标、完整包文件名或裸二进制包名。精确文法见包引用。

sow where

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

sow where 用于回答工作区中哪些 Dist 仍包含某个 Package Object。它默认搜索全部 Repository，只读且不获取写锁。

语法

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

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	将搜索限制到一个 Repository	全部 Repository
`-d, --dist NAME`	将搜索限制到指定 Dist；可重复	全部 Dist
`--json`	输出 `sow.cli/v1` Envelope	false

引用解析

PACKAGE 与 sow show 使用相同文法：SHA-256、规范 RPM/DEB 坐标、完整文件名或裸包名。

sow status

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

sow status 是低成本的 Repository 状态查询。它读取状态，但不哈希文件、不验签、不恢复 Operation、不构建元数据，也不获取写锁。

语法

sow status [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`-d, --dist NAME`	只查看指定 Dist；可重复	全部 Dist
`--json`	输出 `sow.cli/v1` Envelope	false

Repository 状态

每个 Repository 同时跟踪 SQLite 中的 Desired Revision，以及公开 dists/ 树对应的 Built Generation。

sow build

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

sow build 是显式的 Desired-to-Built 收敛命令。它获取 Repository 写锁，恢复任何可裁决的未完成 Operation，渲染并验证完整 Generation，最后切换协议指针。

语法

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

参数	含义	默认值
`-j, --jobs N`	并行 Worker 数，不得小于 `1`	逻辑 CPU 数
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`-d, --dist NAME`	构建指定 Dist；可重复	全部受影响 Dist
`-T, --timeout DUR`	最长等锁时间；`0` 表示无限等待	`0`
`-N, --no-wait`	锁被占用时立即失败	false
`--json`	将结果包装进 `sow.cli/v1` Envelope	false

不带 -d 时，SOW 收敛所选 Repository 中全部受影响 Dist；带 -d 时只收敛指定 Dist，未选择的变化继续保持 dirty。

sow check

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

sow check 是 Managed Repository 的深度只读门禁。它哈希包体、校验状态、重建期望视图并验证已声明签名；不会修复、构建、恢复 Operation，也不会获取写锁。

语法

sow check [-j|--jobs N] [-C|--workdir DIR] [-r|--repo NAME] [-d|--dist NAME]... [--json]

参数	含义	默认值
`-j, --jobs N`	并行校验 Worker 数，不得小于 `1`	逻辑 CPU 数
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`-d, --dist NAME`	校验指定 Dist；可重复	全部 Dist
`--json`	输出 `sow.cli/v1` Envelope	false

校验层

稳态下，checker 按顺序报告九层校验：

sow changes

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

sow changes 比较 Built Generation，输出物理的 Repository 相对文件差异。它不显示尚未构建的 Desired 变化，也不是远端事务协议。

语法

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

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`--json`	输出 `sow.cli/v1` Envelope	false

该命令作用于整个 Repository，明确拒绝 -d/--dist。

sow publish

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

sow publish 将某个 Repository 的当前 Built Generation 交付到 sow.yml 的 targets: 中指定的目标。目标已经绑定 Repository 与 Provider，因此命令不接受 --repo 或 --dist。

语法

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

参数	含义	默认值
`--abort`	放弃已对账、但尚未写入持久 commit intent 的尝试	false
`--rebind`	确认并记录允许修改的目标名称、公共端点或缓存 TTL	false
`-C, --workdir DIR`	工作区发现起点	当前目录
`-T, --timeout DUR`	最长 Repository 等锁时间；`0` 表示无限等待	`0`
`-N, --no-wait`	锁被占用时立即失败	false
`--json`	输出 `sow.cli/v1` Envelope	false

TARGET 必须是已配置的 filesystem 或 r2 发布目标。--abort 与 --rebind 互斥。

sow retain

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

sow retain 管理显式的本地 Generation 根。retain add 只能冻结当前 Built Generation；后续构建使它成为历史版本后，该代所需的软件包体仍受保护。

语法

sow retain add GENERATION [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]
sow retain ls             [-C|--workdir DIR] [-r|--repo NAME] [--json]
sow retain rm GENERATION  [-C|--workdir DIR] [-r|--repo NAME] [-T|--timeout DUR | -N|--no-wait] [--json]

GENERATION 必须是大于零的十进制整数。

sow gc

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

sow gc 有两种严格分离的模式：不带位置目标时，回收本地不可达包体；带 TARGET 时，维护一个已配置发布目标。

语法

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]

参数	含义	默认值
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	仅用于选择本地 GC 的 Repository	选择规则
`-T, --timeout DUR`	最长 Repository 等锁时间；`0` 表示无限等待	`0`
`-N, --no-wait`	锁被占用时立即失败	false
`--json`	输出 `sow.cli/v1` Envelope	false

目标自身已绑定 Repository，因此 gc TARGET -r NAME 属于用法错误。两种模式都不接受 --dist。

sow export

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

SOW 提供一个导出子命令：sow export rpm-leaf。它创建外部、独立的 RPM 仓库， repodata 使用本地 pool/... href。

语法

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

参数	要求
`DIST`	已配置的规范 RPM Dist 名称
`ARCH`	`x86_64` 或 `aarch64`
`DIR`	不存在或为空，且不与 Repository、私有状态、filesystem 目标根重叠的目录

选项	含义	默认值
`--hardlink`	对可信、同文件系统、只读目标使用硬链接	复制文件
`-C, --workdir DIR`	工作区发现起点	当前目录
`-r, --repo NAME`	选择 Repository	选择规则
`--json`	输出 `sow.cli/v1` Envelope	false

该命令不接受 --dist、jobs、timeout 或锁参数。

sow log

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

仓库内的每条写命令，都会先在该仓库的 SQLite 中提交一条应用级 Operation，然后才产生任何外部文件副作用。这条记录让崩溃恢复成为可能——而当 Operation 进入终态之后，同一条记录就是你的审计轨迹。 sow log 读的就是它。