swarmops show#

Show one changeset.

Metadata

Group: read
Since: 0.1.0
Mutates: no
Identity required: no
MCP tool: show
Envelope op: show
Exit codes: 026
Errors: E_NOT_A_REPO E_REV_NOT_FOUND E_INVALID_ARG

Syntax#

swarmops show [OPTIONS] <REV>

Required arguments#

Syntax: <REV>.

The changeset.

Optional arguments#

The command also takes the global options.

Syntax: --max-changes <N>. Default: 400.

The most changes to list.

Examples#

swarmops --repo [tmp]/store show main

{
  "ok": true,
  "op": "show",
  "api": 1,
  "result": {
    "id": "[c2]",
    "seq": 1,
    "parents": [
      "[c1]"
    ],
    "root": "[root2]",
    "author": {
      "agent": "agent/worker-17"
    },
    "created_at": "[created_at]",
    "message": "second",
    "changes": [
      {
        "path": "README.md",
        "op": "put",
        "kind": "file",
        "blob": "[id1]"
      },
      {
        "path": "notes.txt",
        "op": "delete"
      }
    ],
    "files_changed": 2,
    "changes_truncated": false,
    "metadata": {
      "agent": "agent/worker-17"
    },
    "signatures": {
      "author": {
        "name": "agent/worker-17",
        "email": "worker-17@agent.swarmops.local",
        "secs": "[secs]",
        "offset_secs": 0
      },
      "committer": {
        "name": "agent/worker-17",
        "email": "worker-17@agent.swarmops.local",
        "secs": "[secs]",
        "offset_secs": 0
      }
    }
  },
  "meta": {
    "repo": "[tmp]/store",
    "elapsed_ms": "[elapsed_ms]",
    "resolved": {
      "main": "[c2]"
    },
    "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.

No recorded example yet.

Details#

show prints one changeset whole: its place in the store, its parents and root tree, who wrote it and who landed it, its message, the files it changed against its first parent, its metadata and its git signatures. Use it to inspect a change before you land it, after it landed, or when an error names one.

Any changeset, on a ref or not#

REV is any revision, so show reads changesets that no ref names: an agent's commit that has not landed yet, or the actual of an E_CAS_MISMATCH. seq is the changeset's place in the store's index, in commit order, counting every changeset the store holds; it is not a position on main, and the seq values along main can skip numbers.

Who and when#

Field	Holds
`author.agent`	The agent that wrote the change: the `agent` metadata, or `unknown/unknown` when there is none (as for a changeset `git import` made). `author.run_id` is the `run_id` metadata, when present.
`lander`	Only on a changeset a `land` made: the agent that landed it.
`created_at`	The committer signature's time, in Unix milliseconds. For a landed changeset that is when the land published it, not when its author committed.
`signatures`	The git author and committer, kept for git round trips; `secs` in Unix seconds.

A land squashes the change it publishes into one changeset whose parent is the ref's head. Its author is the change's author, squashed_from lists the changesets it squashed (oldest first, ending at the head that was landed), and land_key is the --key of the land, when it had one.

The changes#

changes lists what changed against the first parent, sorted by path: op is put (with the file's kind and blob) or delete. A change of an executable bit alone is a put whose blob did not change. --max-changes (400 by default, at least 1) caps the list; files_changed still counts every path, and changes_truncated says the list was cut. There is no cursor: to see every file of a large changeset, diff it against its first parent (diff REV~1 REV) and page the diff. A changeset made with commit --allow-empty has changes: [] and files_changed: 0.

metadata holds the changeset's SwarmOps metadata as text, such as agent, run_id, commit_key, land_key, lander and squashed_from; a value that is not UTF-8 comes in base64 under its key with :b64 appended.

Patterns#

Review before landing. show <changeset> of a commit an agent reports gives its files and blob ids, cat <changeset>:<path> reads any of them, and diff <base> <changeset> shows what the change did since the base it started from.
Trace a landed change back. On main, show gives lander, land_key and squashed_from; show of each id in squashed_from gives the original commits.
Check a retry. After an E_CAS_MISMATCH, show <actual> gives the winner's agent and run_id metadata: the way to tell another agent's change from your own earlier attempt.
Through MCP, the tool is show, with rev and max_changes. Ask for 100 changes or fewer a call: see Result size limits.

Caveats#

The changes of a merge are those against its first parent: what it brought in from its other parents shows as its own change. Native histories have no merges; histories brought in by git import can.
show lists no renames: a moved file is a delete and a put.
--max-changes 0 is E_INVALID_ARG.

Performance#

show makes its reads in one snapshot. In the v0.1.0 measurement show main took 59.1 µs p50 with no ref but main, 149 µs with 16 more refs and 1.55 ms with 256: a snapshot reads every ref file. See the performance ledger.

Guides#

Return information#

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

Field	Type	Required	Description
`author`	`Attribution`	yes	Who wrote the change.
`changes`	`array of ChangeOut`	yes	What changed relative to the first parent, ordered by path: at most `max_changes` entries.
`changes_truncated`	`boolean`	yes	Whether `changes` stops before the changeset's last change.
`created_at`	`integer`	yes	When it was recorded: the committer signature's time, in Unix milliseconds.
`files_changed`	`integer`	yes	How many paths the changeset changes in all, also when `changes` is truncated.
`id`	`string`	yes	The changeset's id.
`land_key`	`string or null`	no	The idempotency key of the land that made it (its `land_key` metadata), when it had one.
`lander`	`Attribution or null`	no	Who landed it, for a changeset a `land` made: its `lander` and `lander_run_id` metadata. Omitted for any other changeset.
`message`	`string`	yes	The message.
`metadata`	`object`	yes	SwarmOps metadata, such as `agent` and `run_id`. A value that is not UTF-8 is given in standard, padded base64, under its key with `:b64` appended. A commit refuses a key that ends in `:b64`, so `k:b64` is always the base64 of `k`'s value, which is not UTF-8.
`parents`	`array of string`	yes	The parents' ids; the first is the mainline parent that `changes` are relative to.
`root`	`string`	yes	The root tree's id.
`seq`	`integer`	yes	Its position in the store's changeset index, in commit order.
`signatures`	`Signatures`	yes	The git author and committer signatures, kept for git fidelity.
`squashed_from`	`array of string`	no	The changesets a land squashed into it, oldest first: the landed head's first-parent chain after the land's base, ending at that head (its `squashed_from` metadata). Omitted for a changeset no land made.

Envelope op: show.

Exit codes:

0: Success.
2: The request or the command line is malformed.
6: Something the request names does not exist.

Errors#

E_NOT_A_REPO (exit 6): No store at the given path, or no store was named.
E_REV_NOT_FOUND (exit 6): A revision names no changeset.
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).