Page kind: Reference
swarmops ws land#
Land a workspace's chain on its target; with --check, rebase, check and land the checked tree.
Without --check the chain lands as it is (--mode merge). With it the workspace is rebased onto the target, the command runs in the workspace (the ARGV after --, else the repository's check in .swarmops/workspaces.json), and only the tree it ran on is published (--mode exact); a target that moved means rebase and check again, up to --max-attempts. --mode exact without --check publishes the tree of the last ws rebase.
- Group
workspaces- Since
0.3.0- Mutates
- yes
- Identity required
- no
- MCP tool
ws_land- Envelope op
ws_land- Exit codes
- 012
Syntax#
swarmops ws land [OPTIONS] [-- <ARGV>...]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: -m, --message <MSG>.
The landed changeset's message, and the message to commit edits with first.
Syntax: --key <KEY>.
Makes a retry of this land safe: 1 to 64 letters, digits and '-', such as a uuid v7. Make a new one for each change you land, and give it again only to retry that land.
A land with a key first looks down the ref's first parents, to the change's base, for a changeset landed with the same key: one squashed from this HEAD is the land made before, which the land replays (status: replayed) without writing anything; one from another head is E_INVALID_ARG. A key not found there is looked for on the other main, release and branch refs: one that landed on another target is E_INVALID_ARG too, and details.target names the ref. Without a key, the same land run again finds its change on the ref already: E_NOTHING_TO_LAND.
Syntax: --target <REF>.
The ref to land on (default: the workspace's target).
Syntax: --check.
Run a check on the rebased tree before it lands.
Syntax: --check-timeout <S>.
Default: 900.
The most seconds the check runs before it is killed.
Syntax: --mode <MODE>.
merge or exact (default: exact with --check, else merge). Values: merge: Merge onto the target's head, wherever it has moved; exact: Publish only the tree the workspace was rebased to.
Syntax: --max-attempts <N>.
Default: 8.
How many times to rebase, check and land before E_CAS_RETRY_EXHAUSTED: 1 to 32.
Syntax: <ARGV>.
The check's command and arguments, 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#
swarmops --repo [tmp]/store --as agent/worker-17 ws land --ws w3 --mode exactShow 17 more lines
"exit":Exit code 2. 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 WsLandResp (swarmops schema WsLandResp prints its JSON Schema).
| Field | Type | Required | Description |
|---|---|---|---|
attempts | integer | yes | How many rebase, check and land attempts it took. |
land | LandResp | yes | The store's land. |
status_after | WsStatus or null | no | The status after the mutation; omitted when the request said none. |
Envelope op: ws_land.
Exit codes:
0: Success.1: The operation failed.2: The request or the command line is malformed.
Errors#
- E_INVALID_ARG (exit 2): A malformed argument or request, including a command-line usage error.
- E_WS_STALE (exit 1):
ws status,ws diff,ws commit,ws materialize,ws land(onto any target) orws rebase --continuefound the workspace's base gone from its target's history (details.target,base,head;base_op, the operation that moved the target to the base;moved_op, the latest that moved it tohead, or null when not found). - E_CHECK_FAILED (exit 1): A workspace's check or bootstrap command failed or ran past its time (
details.stage:checkorbootstrap;exit_code,timed_out, the tails of its output,log,changeset).
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).