命令

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

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

命令索引

sow create 是 Plain 模式的仓库命令，直接作用于目录。sow init 用于启动 Managed 模式， 必要时会创建 sow.yml；其余有状态命令发现既有工作区。help 与 version 是工具命令， 不需要进入任何模式。

全局语法

sow [OPTIONS] COMMAND [ARGS]

不带参数运行 sow 会打印命令列表并退出 0。用 sow help COMMAND 或 sow help COMMAND SUBCOMMAND 查看内置帮助。sow version 与 sow --version 打印二进制身份。

SOW 没有全局 --format、--yes、--dry-run、-q、-v 或 --config。未知参数直接按 用法错误处理。

工作区发现

Managed 命令按以下规则寻找最近的 sow.yml：

1. 有 -C/--workdir DIR 时从 DIR 开始，否则从当前目录开始。
2. 逐级向上查找，在第一个 sow.yml 停止。
3. 首次查找失败且设置了 SOW_DIR 时，再从该目录查找。显式 -C 会取代当前目录候选， 但不会禁用 SOW_DIR 回退。
4. 仍未发现工作区则退出 2。

--workdir 只改变发现起点，不会切换进程工作目录；相对位置参数仍相对于真实当前目录解析。 sow create 完全不参与工作区发现。

Repository 选择

需要唯一 Repository 的命令按以下顺序选择：

1. 显式 -r/--repo NAME；
2. 发现起点所在的 Repository；
3. 工作区中唯一的 Repository；
4. 否则退出 2 并列出候选项。

repo new 与 repo rm 用位置参数接收 NAME，不接受 -r。sow where 默认搜索所有 Repository，-r 只用于收窄范围。发布目标自身绑定 Repository，因此 publish TARGET 与 gc TARGET 不再接受额外的 Repository 选择。

Dist 选择

add、rm、ls 要求明确的 Dist 集合，并按以下顺序选择：

1. 一个或多个 -d/--dist NAME；
2. 发现起点所在的 Dist；
3. 所选 Repository 中唯一的 Dist；
4. 否则退出 2 并列出候选项。

其他命令有意采用不同规则：

• 未指定 -d 时，build、check、status 默认作用于全部 Dist；
• show 默认搜索所选 Repository，-d 只用于收窄；
• where 默认跨工作区搜索全部匹配 Dist，-r/-d 用于收窄；
• changes 作用于整个 Repository，明确拒绝 -d。

锁

除 init 外，写命令接受 -T/--timeout DUR 与 -N/--no-wait。init 获取 Workspace 锁，且不提供 命令行超时覆盖；其他锁均为 Repository 级，但 repo new 与 repo rm 同样使用 Workspace 锁。 --timeout 0 表示无限等待；正数使用 Go duration，例如 500ms、30s、5m。--no-wait 立即失败；它与正数 timeout 互斥。获取锁失败退出 4。

只读命令不获取写锁；status 仍会报告 Repository 是否正被写者持锁。

并发

只有需要解析软件包、哈希包体、渲染索引或执行校验的命令才接受 -j/--jobs N：create、 add、rm、build、check 与 repo migrate。默认值是逻辑 CPU 数，且不得小于 1。

JSON 输出

支持 --json 的命令在 stdout 输出一个带版本的 Envelope，诊断信息仍写入 stderr：

{
  "schema": "sow.cli/v1",
  "command": "add",
  "ok": true,
  "repository": "demo",
  "operation": "1430722512865805553",
  "result": {},
  "errors": []
}

任何非零退出都会令 ok 为 false；部分成功的批处理仍会返回已提交项与失败项。完整结果结构见 JSON 输出。

不带 --json 时，每条 Managed 命令都有稳定的人类可读 renderer，适合交互使用，但不属于机器 协议。需要结构化字段的脚本应始终使用 --json；它也是唯一受支持的机器接口。

退出码

各命令的精确触发条件见退出码。