generation on SOW

SOW v0.2.0

Sat, 08 Aug 2026 00:00:00 +0000

SOW 0.2.0 是 Pigsty 出品的自包含 RPM/DEB 仓库管理器，Release 资产以单个 Go 可执行文件覆盖 Linux 与 macOS 构建目标。

两种工作模式

Plain 模式 给目录顶层已有的 RPM 与 DEB 文件就地生成索引：

系统模型

Sat, 08 Aug 2026 00:00:00 +0000

SOW 刻意把模型分层：配置表达意图，数据库记录有主状态，公共树是确定性投影。任何一层都不能悄悄替代另一层。

对象层级

Workspace
├── Repository
│   ├── Package Object
│   ├── Dist
│   │   └── Membership -> Package Object
│   ├── Desired 状态
│   ├── Built Generation
│   └── Retained Generation 引用
└── Publication Target
    └── Repository + provider + prefix

Workspace

Workspace 提供发现、配置与协调，拥有 sow.yml、私有 .sow/ 目录和稳定锁路径；它不是包体去重域。

Managed 工作区

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

当同一个仓库要维护好几个月 —— 包成批到达、由策略决定谁留下、事后还得说清楚什么时候变了什么 —— 你需要的是 Managed 模式。本页讲三层模型、它产出的布局,以及命令怎么判断你说的是哪个仓库、哪个 Dist。

第一个工作区

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

Managed 模式会持久保存配置、成员关系、Generation 与审计状态。下面从空目录开始。

初始化工作区

sow init /srv/sow
cd /srv/sow

init 创建：

事务与恢复

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

本页说明 Managed 模式如何防止 live 指针指向缺失内容，以及如何协调 SQLite 状态与文件系统变更。

不变式

在受支持的本地 POSIX 文件系统上，沿 Managed 协议指针读取的客户端只会得到完整旧视图或完整新视图，包括进程中断之后。

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 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 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 必须是大于零的十进制整数。