Reference on SOW

sow.yml 配置参考

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

sow.yml 是 Managed 托管工作区(Workspace)唯一的配置文件。它位于工作区根目录, 声明存在哪些仓库(Repository)与 Dist,并保存每次构建都要执行的成员策略与签名设置。 Plain 平面模式(sow create)完全不读它。

包引用

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

sow rm、sow show、sow where 都接受一个 PACKAGE 参数。本页定义你能在那里写什么。三条命令共用同一套文法,只有对 歧义名称 的处理不同。

这里的内容与 sow add 无关 —— add 接受的是文件系统路径,不是包引用。

参考

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

这一部分记录配置字段、包引用、路径、退出码、JSON、平台与集成等稳定契约。CLI 语法和状态变化见命令，使用模型见上手。

输出示例只说明形态；标识符、路径、哈希、时间戳与计数会随工作区变化。二进制自带的 sow help 始终是精确语法权威。

仓库布局

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

SOW 的 Managed 布局只有一种：软件包体在 pool/ 下只存一份，dists/ 只保存客户端视图元数据。对外服务、复制或发布时,单位始终是完整仓库目录。

Plain 模式

sow create 在现有软件包旁写入索引,不修改无关文件:

退出码

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

每条 sow 命令都以七个退出码之一结束。它们是稳定的、对所有命令一致, 并且就是设计来给脚本做分支判断的 —— 区分"这件事失败了"和"这件事被正确地拒绝了", 正是设置多个非零码的全部意义。

JSON 输出

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

所有产出数据的命令都接受 --json。输出是 stdout 上的一行版本化信封 —— 不管是哪条命令产生的,都能直接管道给 jq。

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":"00000000000000000004","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":[]}

(此处为便于阅读做了折行,实际输出是一行。)

平台与集成

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

本页说明 SOW 提供哪些构建目标、工作区依赖什么存储语义，以及自动化集成具体覆盖哪些行为。仓库生成在 SOW 二进制内部完成；部署后的最终门禁仍是实际软件包管理器。