swarmops ws rebase#

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

Move a workspace's chain onto its target's head, and its files with it.

Edits on disk are snapshotted first and carried onto the new head; those that do not apply take the new head's files and stay in the snapshot, named as kept. On a conflict the workspace holds markers: edit them, ws resolve, then ws rebase --continue. --abort leaves the rebase and restores the conflicting paths.

Metadata

Group: workspaces
Since: 0.3.0
Mutates: yes
Identity required: no
MCP tool: ws_rebase
Envelope op: ws_rebase
Exit codes: 013
Errors: E_CONFLICT E_UNRESOLVED_CONFLICTS

Syntax#

Syntax

swarmops ws rebase [OPTIONS]

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: --onto <REF>. Default: main.

The ref to rebase onto: main or release/<name>, and in a FORMAT 2 store a branch (feature/x) or a tag (tags/v1).

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

Commit the workspace's edits first, with this message (default: a snapshot of them).

Syntax: --continue.

Rebase again once the conflicts are resolved.

Syntax: --abort.

Leave the rebase.

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 rebase --ws w2 --onto release/ws

Output, an error

{ "ok": false, "op": "ws_rebase", "api": 1, "error": { "code": "E_CONFLICT", "message": "1 path(s) of the change conflict with the target's head [id15]: nothing was recorded", "retryable": false,

Show 63 more lines

"exit": 3, "details": { "report": { "base": "[c1]", "files": [ { "base_blob": "[id10]", "hunks": [ { "base": { "first": 1, "last": 1, "text": "pub fn f() {}\n" }, "id": 0, "ours": { "first": 1, "last": 1, "text": "pub fn mine() {}\n" }, "theirs": { "first": 1, "last": 1, "text": "pub fn moved_on() {}\n" } } ], "kind": "content", "ours_blob": "[id17]", "path": "src/lib.rs", "theirs_agent": "agent/worker-17", "theirs_blob": "[id18]", "theirs_changeset": "[id15]", "theirs_changesets": [ { "agent": "agent/worker-17", "changeset": "[id15]" } ] } ], "kinds": [ "content" ], "ours": "[id14]", "theirs": "[id15]", "truncated": false } }, "hint": "swarmops cat [id15]:src/lib.rs, then swarmops land [id14] --resolve <file> (resolutions over MCP) with each path's resolution and against = [id15]" }, "meta": { "repo": "[tmp]/store", "elapsed_ms": "[elapsed_ms]", "resolved": { "[c1]": "[c1]", "[id14]": "[id14]", "[id15]": "[id15]", "release/ws": "[id15]" }, "auth": "trust" } }

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

Field	Type	Required	Description
`changeset`	`string`	yes	The workspace's head now.
`dropped`	`array of string`	no	The paths whose edits did not apply: the files hold the new head's, `kept` the edits.
`kept`	`string or null`	no	The snapshot again, when some of its edits did not apply to the new head: it keeps them by id.
`onto`	`string`	yes	The target's head it was rebased onto.
`snapshot`	`string or null`	no	The changeset that holds the edits on disk when the update started, on the old head; omitted when there were none.
`status`	`RebaseStatus or null`	no	How the rebase ended; `None` after an abort.
`status_after`	`WsStatus or null`	no	The status after the mutation; omitted when the request said `none`.

Envelope op: ws_rebase.

Exit codes:

0: Success.
1: The operation failed.
3: The change conflicts with what it lands on: resolve it, then run the operation again.

Errors#

E_CONFLICT (exit 3): The change conflicts with the target: details.report lists each conflicting file with its kind, its hunks and who changed it on the target.
E_UNRESOLVED_CONFLICTS (exit 1): A rebase still has conflicting paths no one resolved (details.paths).

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