swarmops commit#

Record a changeset from a list of changes; with --advance, also move that ref to it.

Syntax#

swarmops commit [OPTIONS] --message <MESSAGE> --changes <FILE>

Required arguments#

Optional arguments#

The command also takes the global options.

Examples#

SWARMOPS_RUN_ID=run-1 swarmops --repo [tmp]/store --as agent/worker-17 commit -m 'first commit

with a body' --changes [tmp]/changes.json

{
  "ok": true,
  "op": "commit",
  "api": 1,
  "result": {
    "changeset": "[c1]",
    "root": "[root1]",
    "files_changed": 6,
    "blobs_written": 6,
    "replayed": false
  },
  "meta": {
    "repo": "[tmp]/store",
    "elapsed_ms": "[elapsed_ms]",
    "resolved": {},
    "auth": "trust"
  }
}

Details#

commit records one changeset from an explicit list of changes, relative to a parent. There is no working copy and no staging area: the change list is the whole input. Without --advance it moves no ref: the change is published by landing it (land) or by moving a ref to it (ref set). Commit and land walks through the whole flow.

The parent#

The changeset is built on, in this order of precedence:

1. --parent REV, when given: any revision, resolved once, in the snapshot the commit reads in.
2. Else, with --advance REF, REF's head as it is when the command runs, or nothing when REF does not exist (a root commit that creates REF).
3. Else main's head as it is when the command runs, or nothing when main does not exist (a root commit).

A head taken by default is recorded in meta.resolved under the ref's name. Once main exists, a root commit needs --advance naming a ref that does not exist yet.

Give --parent as the full id you read the content at. A head read at commit time is not necessarily the one your edits were based on: another agent may have moved it in between.

The change list#

--changes FILE reads a JSON array of changes from FILE, or from stdin for -, at most 64 MiB of text. Each change is:

{"path": "src/lib.rs", "op": "put", "content": {"inline": "fn main() {}\n"}, "mode": "file"}

• path: a repository path, /-separated and relative, with no empty, . or .. component and no NUL. Each path may appear in one change only.
• op: put writes the path, creating or replacing the entry; delete removes it and takes neither content nor mode.
• content, for a put, one of four forms: {"inline": text} (UTF-8, verbatim), {"base64": text} (standard, padded), {"file": path} (a file on this host, read by the command, a relative path taken from the current directory) or {"blob": id} (a blob the store holds already, from blob put, by its 64 hex digits).
• mode: file (the default), exec or symlink, whose content is the link's target.

The whole list is checked before any content is decoded or read, and a refused list writes nothing. Write a change list shows renames, moves and the refusals in full; swarmops schema ChangeInput gives the schema.

Limits#

Contents are measured by the sizes they declare (inline text's length, the bytes base64 decodes to, a file's length) before any is read. A blob named by id counts toward none of them, so large files go in with blob put first and are named by id.

What is recorded#

The changeset's author and committer are both your agent name, with the email <instance>@<family>.swarmops.local, at the current time to the second, UTC. Its metadata holds agent, run_id when you have one, and commit_key with --key. files_changed counts the paths the changeset changes: a put of what a path holds already is no change. A list that changes nothing is E_EMPTY_COMMIT (exit 1) unless --allow-empty is given.

--advance: commit and publish in one transaction#

With --advance REF, the changeset and REF's move to it are one write transaction, one journal frame, where commit then ref set --expect take two. REF must be main or release/<name>; any other name is E_REF_NAME_INVALID. The move is a compare-and-swap against the parent: when REF names anything else, nothing is recorded, neither the changeset nor the move, and the commit fails with E_CAS_MISMATCH (exit 4, retryable), its details.actual naming what REF holds and details.committed false. The result's advanced reports the move: name, old (left out when the move created REF), new and already_applied.

--advance publishes without a merge: it suits a single writer of a ref, or a script that re-applies its edits on a failure. With several agents writing at once, commit without it and land, which merges onto whatever the ref holds by then (Publish without a land). Through MCP, advance needs parent as a full 64-hex id.

--key: a retry that is safe#

--key takes a uuid v7, any case; anything else is E_INVALID_ARG, before anything is read. The commit then signs at the key's time instead of the clock's, and records the key, so the same command run again on the same parent, by the same agent with the same run id, is the same changeset: the second run says replayed: true, with blobs_written 0, and writes nothing. A different agent with the same key makes a different changeset, since the agent name is part of what is signed and recorded. Make a new key for each commit; Commit keys and Idempotency keys give a generator.

Patterns#

• The two-step publish of an agent: read main's id, commit on it with --parent, then land the result with a land key (Publish a change).
• A chain of commits, each with --parent the one before, landed at once by landing the last: the land squashes the chain (Land a chain of commits).
• Generated content from a pipe: --changes - reads the list from stdin. A change's file content may not then name this process's own stdin or stdout (E_INVALID_ARG): send such bytes inline or in base64.

Failures#

Exit 4 is retryable; Retry rules say how. After E_CAS_MISMATCH, do not re-send your old whole-file puts on top of actual: they would revert what the winner changed in the same files.

Performance#

On the reference host of the v0.1.0 measurement, one commit alone took 19 ms (meta.elapsed_ms, p50); the M1 runs found nearly all of an uncontended commit's time in its fsyncs. 32 processes committing at once through the binary made 71.7 commits/s together, a commit taking 433 ms at the median and 621 ms at p99, mostly its wait for the store's lock, with no E_BUSY. What --advance saves under contention is not measured yet (publishes under 32 writers).

Return information#

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

Envelope op: commit.

Exit codes:

• 0: Success.
• 1: The operation failed.
• 2: The request or the command line is malformed.
• 4: The operation can succeed when it is run again.
• 5: An identity or policy requirement refused the operation.

Errors#

• E_IDENTITY_REQUIRED (exit 5): A mutation was asked for without an identity.
• E_TOO_LARGE (exit 1): The content is larger than the operation allows.
• E_EMPTY_COMMIT (exit 1): The commit changes nothing and allow_empty is off.
• E_TYPE_CONFLICT (exit 1): A change puts an entry below a file, or a file onto a directory.
• E_CAS_MISMATCH (exit 4): The ref no longer holds the expected target (or, with create, exists at another one); details.actual holds what it does, null when the ref does not exist.
• E_INVALID_ARG (exit 2): A malformed argument or request, including a command-line usage error.

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

See also#

• Operating SwarmOps: Agents commit and land
• swarmops land
• swarmops blob put
• swarmops blob has
• CLI reference
• Error codes