跳转到主要内容

sow status

快速读取 Repository 的收敛、可交付、待处理包体、最近 Operation 与锁状态。

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。

状态 含义 公开视图
clean Desired 与 Built 一致 当前且完整的 Generation
dirty Desired 已领先，常见于 --skip 或配置变化之后 上一个完整 Generation
recovering 存在非终态 Operation，下一条写命令必须先恢复 上一个已完成的协议指针
error 自动恢复无法安全裁决 保留上一个完整视图，不尝试覆盖

dirty 不代表仓库只写了一半。协议指针最后切换，因此读者看到的始终是完整旧视图或完整新视图。

输出 

sow status -r pgsql
repository=pgsql status=dirty ready_to_copy=false revision=4 generation=3 dirty_dists=trixie pending=4/2326 locked=false

人类可读输出包含 Repository 状态、ready_to_copy、Desired Revision、Built Generation、 受影响 Dist、待处理对象数量/字节数与写锁状态。

JSON 结果还包含 dirty_reasons 与最近一次 Operation：

{
  "repository": "demo",
  "status": "dirty",
  "ready_to_copy": false,
  "desired_revision": 5,
  "built_generation": "00000000000000000004",
  "dirty_dists": ["el9"],
  "dirty_reasons": ["dist el9 Desired and Built membership sets differ"],
  "pending": {"count": 1, "bytes": 19776},
  "repository_locked": false
}

ready_to_copy=false 是明确警告；true 只是廉价状态判断，并非字节级完整性证明。交付前应运行 sow check。

只读契约

status 不迁移也不修复状态。Repository 数据库无法安全读取时，命令退出 5；请先执行 诊断信息明确指出的维护命令，再重新查询。尤其是 v0.3 Repository，使用 0.4 读取表面前必须先 备份，并逐个执行 sow repo migrate。

退出行为

只要状态可读，status 在 clean、dirty、recovering、error 四种状态下都返回 0。 脚本应读取结构化状态，而不是把后三者当作命令执行失败。

代码 触发条件
0 Repository 状态可读
1 运行时 I/O 错误
2 用法错误、未发现工作区或隐式 Repository 选择有歧义
5 状态库不可读或不一致
6 显式指定的 Repository 或 Dist 未配置

参见

最后修改 2026-08-28 · commit 781b3cc