swarmops ws commit#

Describes v0.11.0Last changed 2026-11-08View as Markdown

Record a workspace's edits as one changeset on its head.

Metadata

Group: workspaces
Since: 0.3.0
Mutates: yes
Identity required: no
MCP tool: ws_commit
Envelope op: ws_commit
Exit codes: 01
Errors: E_WS_OUTSIDE_PREFIXES

Syntax#

Syntax

swarmops ws commit [OPTIONS] --message <MESSAGE> [PATH]...

Required arguments#

Syntax: -m, --message <MESSAGE>.

The changeset's message.

Optional arguments#

The command also takes the global options.

Syntax: --ws <NAME>.

The workspace, by its name in the store's registry (default: the one around the working directory).

Syntax: --ws-path <DIR>.

The workspace's directory.

Syntax: <PATH>.

Only these repository paths (default: every change).

Syntax: --mode <PATH=KIND>....

The kind to record for a path, where the volume cannot hold the executable bit: PATH=file, PATH=exec or PATH=symlink; repeatable.

Syntax: --status-after <STATUS_AFTER>. Default: page.

page: the first page of the status follows the result; none: it is left out. Values: page: The first page of the status; none: No status.

Examples#

Shell

swarmops --repo [tmp]/store --as agent/worker-17 ws commit --ws w3 -m third

Output

{ "ok": true, "op": "ws_commit", "api": 1, "result": { "changeset": "[id13]", "parent": "[c1]", "files_changed": 1,

Show 23 more lines

"blobs_written": 1, "replayed": false, "status_after": { "name": "w3", "base": "[c1]", "head": "[id13]", "main": "[c1]", "behind_by": 0, "state": "clean", "changes": [], "truncated": false } }, "meta": { "repo": "[tmp]/store", "elapsed_ms": "[elapsed_ms]", "resolved": { "[c1]": "[c1]", "main": "[c1]" }, "auth": "trust" } }

Exit code 0. Recorded by the CLI tests. A name in square brackets, such as [tmp] or [c1], stands for what differs from run to run: the test's temporary directory, an id, a time.

No recorded example yet.

Return information#

result is a WsCommitResp (swarmops schema WsCommitResp prints its JSON Schema).

Field	Type	Required	Description
`blobs_written`	`integer`	yes	How many blobs the store did not hold and got.
`changeset`	`string`	yes	The new changeset: the workspace's head now.
`files_changed`	`integer`	yes	How many paths it changes.
`parent`	`string`	yes	Its parent: the head before.
`replayed`	`boolean`	yes	A crashed commit's key replayed: the changeset was recorded before.
`status_after`	`WsStatus or null`	no	The status after the mutation; omitted when the request said `none`.

Envelope op: ws_commit.

Exit codes:

0: Success.
1: The operation failed.

Errors#

E_WS_OUTSIDE_PREFIXES (exit 1): A sparse workspace's ws commit or ws land met edits outside its prefixes (details.paths, sorted, the first 20).

Any command that opens a store may also fail with a store error, such as E_NOT_A_REPO, E_IO or E_STORE_CORRUPT; a command line the grammar refuses is E_INVALID_ARG (exit 2).