swarmops ws discard#

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

Restore paths of a workspace from its head, every changed one without a PATH: the edits are lost.

Metadata

Group: workspaces
Since: 0.3.0
Mutates: yes
Identity required: no
MCP tool: ws_discard
Envelope op: ws_discard
Exit codes: 04
Errors: E_WS_LOCKED

Syntax#

Syntax

swarmops ws discard [OPTIONS] [PATH]...

Required arguments#

None.

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>.

The repository paths to restore.

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 discard --ws w1

Output, an error

{ "ok": false, "op": "ws_discard", "api": 1, "error": { "code": "E_WS_LOCKED", "message": "another mutation of this workspace held its lock for 5 s", "retryable": true,

Show 11 more lines

"exit": 4, "details": {}, "hint": "run the command again once the other one has finished" }, "meta": { "repo": "[tmp]/store", "elapsed_ms": "[elapsed_ms]", "resolved": {}, "auth": "trust" } }

Exit code 4. 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 WsDiscardResp (swarmops schema WsDiscardResp prints its JSON Schema).

Field	Type	Required	Description
`discarded`	`array of string`	yes	The paths restored.
`status_after`	`WsStatus or null`	no	The status after the mutation; omitted when the request said `none`.

Envelope op: ws_discard.

Exit codes:

0: Success.
4: The operation can succeed when it is run again.

Errors#

E_WS_LOCKED (exit 4): Another mutation held the workspace's lock for the whole wait (details.holder, when it is known); running the operation again can succeed.

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).