# swarmops ws commit

> Release: 0.11.0 · Last changed: 2026-11-08 · Source: https://github.com/KeiaiLab/SwarmOps/blob/stable/docs/reference/commands/ws-commit.md

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

```yaml
title: "swarmops ws commit"
description: "Record a workspace's edits as one changeset on its head."
group: "workspaces"
since: "0.3.0"
mutates: true
identity_required: false
mcp_tool: "ws_commit"
envelope_op: "ws_commit"
exit_codes: [0, 1]
errors: [E_WS_OUTSIDE_PREFIXES]
syntax: "swarmops ws commit [OPTIONS] --message <MESSAGE> [PATH]..."
```

## Syntax

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

## Required arguments

### `--message`

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

The changeset's message.

## Optional arguments

The command also takes the [global options](../cli.md#global-options).

### `--ws`

Syntax: `--ws <NAME>`.

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

### `--ws-path`

Syntax: `--ws-path <DIR>`.

The workspace's directory.

### `PATH`

Syntax: `<PATH>`.

Only these repository paths (default: every change).

### `--mode`

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.

### `--status-after`

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

### CLI

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

```json
{
  "ok": true,
  "op": "ws_commit",
  "api": 1,
  "result": {
    "changeset": "[id13]",
    "parent": "[c1]",
    "files_changed": 1,
    "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.

### MCP

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`](../errors.md#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`](../errors.md#e_not_a_repo), [`E_IO`](../errors.md#e_io) or [`E_STORE_CORRUPT`](../errors.md#e_store_corrupt); a command line the grammar refuses is [`E_INVALID_ARG`](../errors.md#e_invalid_arg) (exit 2).

## See also

- [`swarmops ws create`](ws-create.md)
- [`swarmops ws status`](ws-status.md)
- [`swarmops ws diff`](ws-diff.md)
- [`swarmops ws rebase`](ws-rebase.md)
- [`swarmops ws resolve`](ws-resolve.md)
- [`swarmops ws land`](ws-land.md)
- [`swarmops ws materialize`](ws-materialize.md)
- [`swarmops ws discard`](ws-discard.md)
- [`swarmops ws snapshot`](ws-snapshot.md)
- [`swarmops ws list`](ws-list.md)
- [`swarmops ws info`](ws-info.md)
- [`swarmops ws delete`](ws-delete.md)
- [`swarmops ws hook`](ws-hook.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)