包引用

命令行上指代一个软件包的五种写法,以及歧义如何裁决。

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

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

五种形态

形态例子匹配
内容摘要sha256:d06d7f23b9cf...b98b1229恰好一个包对象
RPM 坐标rpm:pev2-0:1.23.0-1.noarch恰好一个 RPM
DEB 坐标deb:libpq5=18.3-1.pgdg12+1:amd64恰好一个 DEB
完整文件名pev2-1.23.0-1.noarch.rpm以该文件名存储的包
裸包名pev2该名称的全部版本与架构

前三种是精确引用:指名道姓,要么命中要么失败。后两种是便利写法,可能匹配多个对象。

你不需要手工拼这些字符串。sow ls 会直接打印每个包的摘要与坐标,可以原样粘回命令行:

sow ls -d el9

repository=pigsty dists=el9 dirty=false
SHA256	COORDINATE	DISTS	BUILT_DISTS	POOL_PATH
sha256:ceb1b8660f8bc1fe59fb7a28e750e19a1ccd010a254a50e82328adb5818a5943	rpm:blackbox_exporter-0:0.28.0-1.aarch64	el9	el9	pool/b/blackbox_exporter/blackbox_exporter-0.28.0-1.aarch64.rpm
sha256:5759c643a789631346e3ed315a696a0118f81f7cc3c65e5a4385a876983d3a18	rpm:blackbox_exporter-0:0.28.0-1.x86_64	el9	el9	pool/b/blackbox_exporter/blackbox_exporter-0.28.0-1.x86_64.rpm
sha256:d06d7f23b9cfc6aedaab7b60c8e890cda020efe84f1f246243414862b98b1229	rpm:pev2-0:1.23.0-1.noarch	el9	el9	pool/p/pev2/pev2-1.23.0-1.noarch.rpm

内容摘要

sha256:<64 位小写十六进制>

已存储包体完整字节的 SHA-256。这是 SOW 里最强的引用形式:它就是对象身份,不可能有歧义。

sow where sha256:d06d7f23b9cfc6aedaab7b60c8e890cda020efe84f1f246243414862b98b1229

{"reference":"sha256:d06d7f23...b98b1229","locations":[{"repository":"pigsty","dists":["el9"],"built_dists":["el9"],"sha256":"d06d7f23...b98b1229","coordinate":"rpm:pev2-0:1.23.0-1.noarch"}]}

摘要必须完整且小写。不支持前缀匹配,也不做大小写折叠 —— 位数不足或大写都属于用法拒绝, 不是"没找到":

operation rejected: managed: operation rejected: sha256 reference requires 64 lowercase hexadecimal digits

注意这个摘要覆盖的是已存储的字节。如果仓库对 RPM 包体做了重签, 对象摘要与你交给 sow add 的那个文件的摘要就不一样了。

RPM 坐标

rpm:<name>-<epoch>:<version>-<release>.<arch>

完整 NEVRA,加 rpm: 前缀。每一段都必填,包括 epoch —— 包本身没有 epoch 时写 0。

sow where 'rpm:pev2-0:1.23.0-1.noarch'

在 shell 里请加引号:NEVRA 含冒号,否则可能被历史展开或路径补全改写。

前缀与 epoch 都是必需的。少任何一个,这串字符就会被当成裸名解析,从而什么都找不到:

sow where 'rpm:pev2-1.23.0-1.noarch'
operation rejected: managed: operation rejected: package reference "rpm:pev2-1.23.0-1.noarch" was not found in the selected Workspace scope

架构那一段取自 RPM 包头:x86_64、aarch64 或 noarch。它不是规范族名 —— noarch 包这里就写 noarch,尽管 SOW 内部把它归类为 neutral(中性)。

DEB 坐标

deb:<package>=<version>:<architecture>

Debian 身份三元组,加 deb: 前缀。版本是含 epoch 与 revision 的完整 Debian 版本号; 架构是生态名(amd64、arm64、all),不是规范族名。

sow where 'deb:libpq5=18.3-1.pgdg12+1:amd64'

三段都必填。deb:libpq5=18.3-1.pgdg12+1 不带架构,匹配不到任何东西。

完整文件名

包存储时的完整文件名,含扩展名:

sow where 'pev2-1.23.0-1.noarch.rpm'
sow where 'libpq5_18.3-1.pgdg12+1_amd64.deb'

看着目录列表操作时,这是最好敲的写法。但它不是身份 —— SOW 不用文件名区分包, 理论上两个不同对象可以叫同一个名字。脚本里请优先用坐标或摘要。

裸包名

只写二进制包名:

sow where pev2

它的含义取决于命令:

  • sow rm 把它理解为所选 Dist 中该名称的全部版本与原生架构。这是有意设计的 —— 下架一个包通常意味着全部下架。先用 -c 预览:

    sow rm libpq5 -d trixie -c

    {"repository":"pigsty","desired_revision":10,"built_generation":10,"dirty":false,"check":true,
 "removed":[{"dist":"trixie","sha256":"310611d0...","coordinate":"deb:libpq5=18.2-1.pgdg12+1:amd64","name":"libpq5"},
            {"dist":"trixie","sha256":"4b526223...","coordinate":"deb:libpq5=18.3-1.pgdg12+1:amd64","name":"libpq5"},
            {"dist":"trixie","sha256":"cadeb929...","coordinate":"deb:libpq5=18.3-1.pgdg12+1:arm64","name":"libpq5"}], ...}

  • sow show 与 sow where 要求它唯一命中。这两条命令描述的是单个包, 名称匹配多个时会连同候选列表一起拒绝:

    operation rejected: managed: operation rejected: package reference "libpq5" is ambiguous: deb:libpq5=18.2-1.pgdg12+1:amd64 sha256:310611d0fea1ce82644f48d90d485c60738b21e52ab5a60e1de43875bdfef601, deb:libpq5=18.3-1.pgdg12+1:amd64 sha256:4b5262231787caf1f367f5c8705a8a03d3176c31a15e6096946d50514db128be, deb:libpq5=18.3-1.pgdg12+1:arm64 sha256:cadeb9294901ac5ae6228bd3471c444cc288d9894af0dd0730909596d9dfcefb

    每个候选都同时给出坐标与摘要,所以修正方式就是把其中一条粘回命令行。

哪些写法不成立

不带 rpm: 前缀的 NEVRA 看起来像坐标,实际会被当作裸名解析, 而裸名里不含 epoch 和架构:

sow rm 'pev2-0:1.23.0-1.noarch' -d el9 -c
operation rejected: managed: operation rejected: package reference not found: package reference "pev2-0:1.23.0-1.noarch" matches no Desired Membership

另外,这里没有 glob、没有正则、没有版本区间,也没有 --all 参数。 如果你想按模式筛选一批包,那是 sow.yml 里的成员策略, 不是命令行选择器。命令行永远只用来指代已经存在的包。

作用域

引用总是在某个作用域内解析,而作用域由常规的选择参数决定,与引用写法无关:

命令默认作用域收窄方式
sow rm所选仓库的所选 Dist-r、-d(存在多个时必填)
sow show所选仓库-r、-d
sow where工作区内全部仓库-r、-d

sow where 是那条"广搜"命令 —— 当你知道某个包在某处、但不知道在哪个仓库时用它。 sow show 则是在一个仓库内把一个对象的细节全部展开。

两条命令没找到时的措辞也不同,可以据此判断自己跑的是哪一条:

# rm —— 引用本身解析成功,但所选 Dist 里没有对应成员
operation rejected: ... package reference "nosuchpkg" matches no Desired Membership

# show / where —— 搜索范围内根本不存在
operation rejected: ... package reference "nosuchpkg" was not found in the selected Workspace scope

坐标与身份

上面的坐标形态是包的逻辑身份。SOW 强制约束:一个仓库内,一个坐标最多对应一个内容对象。 用已存在的坐标加入一个不同的文件是硬冲突 —— SOW 不会悄悄挑一个赢家,也没有 --replace。

因此,两个只有签名不同的包仍然会冲突,因为它们坐标相同。如果你真的要重签发布, 请提高 release 号;如果只是把同一个输入再加一次,SOW 会识别出来并报告 reused。

延伸阅读

最后修改：2026-08-08: init commit (fe725aa)