diff#

The files that differ between two revisions, in path order: with format names (the default) each one's path and status, with stat also its line counts, with unified also its hunks; pass a limit of 100 or less, keep max_bytes at 32768 or less for unified, and page on with the cursor, since clients limit long tool results.

Metadata

Since: 0.1.0
Mutates: no
Identity required: no
Envelope op: diff
Cli command: swarmops diff
Request type: DiffReq
Annotations: {"destructiveHint":false,"idempotentHint":true,"openWorldHint":false,"readOnlyHint":true}
Max result chars: null
CLI command: swarmops diff

Input schema#

arguments is a DiffReq: swarmops schema DiffReq prints the type. A field the type does not know is ignored.

Field	Type	Required	Default	Description
`context`	integer	no	`3`	The unchanged lines around each change in a `unified` hunk.
`cursor`	string or null	no		Resume a diff: the previous page's `cursor`. Pass it back exactly as returned; do not construct it (cursors are opaque). This page starts after the file it names.
`format`	string	no	`"names"`	What to say of each file: `names` its path and status; `stat` also whether it is binary and, for text, the lines it inserts and deletes; `unified` also its kinds, its blobs and, for text, its hunks. What `diff` says of each file.
`from`	string	yes		The revision to diff from: the old side. A revision as the caller wrote it, for the store to resolve: a ref name (`main`, `release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits, optionally followed by `~N` for the N-th first-parent ancestor.
`limit`	integer	no	`500`	The most files to return: at least 1 (0 is `E_INVALID_ARG`).
`max_bytes`	integer	no	`32768`	The most bytes a `unified` page's files take, as the JSON array `files` they print as: at least 1 (0 is `E_INVALID_ARG`). The page stops before the first file that would take it past this, but always holds one file, whose hunks are cut to the first ones that fit (`hunks_truncated`) when they alone would pass it. A `names` or `stat` page is held by `limit` alone.
`paths`	array of string	no		Only the files at or below these repository paths (a file's path takes that file; one trailing `/` is taken); every file when empty or omitted.
`to`	string	yes		The revision to diff to: the new side. A revision as the caller wrote it, for the store to resolve: a ref name (`main`, `release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits, optionally followed by `~N` for the N-th first-parent ancestor.

JSON Schema#

As tools/list gives it: each $ref replaced by its definition, so that it stands alone.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "`diff`: the files that differ between two revisions, in path order, a page at a time.",
  "properties": {
    "context": {
      "default": 3,
      "description": "The unchanged lines around each change in a `unified` hunk.",
      "format": "uint32",
      "minimum": 0,
      "type": "integer"
    },
    "cursor": {
      "description": "Resume a diff: the previous page's `cursor`. Pass it back exactly as returned; do not\nconstruct it (cursors are opaque). This page starts after the file it names.",
      "type": [
        "string",
        "null"
      ]
    },
    "format": {
      "default": "names",
      "description": "What to say of each file: `names` its path and status; `stat` also whether it is binary\nand, for text, the lines it inserts and deletes; `unified` also its kinds, its blobs and,\nfor text, its hunks. What `diff` says of each file.",
      "oneOf": [
        {
          "const": "names",
          "description": "Its path and status.",
          "type": "string"
        },
        {
          "const": "stat",
          "description": "Also whether it is binary and, for text, the lines it inserts and deletes.",
          "type": "string"
        },
        {
          "const": "unified",
          "description": "Also its kinds, its blobs and, for text, its hunks.",
          "type": "string"
        }
      ]
    },
    "from": {
      "description": "The revision to diff from: the old side. A revision as the caller wrote it, for the store to resolve: a ref name (`main`,\n`release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits,\noptionally followed by `~N` for the N-th first-parent ancestor.",
      "type": "string"
    },
    "limit": {
      "default": 500,
      "description": "The most files to return: at least 1 (0 is `E_INVALID_ARG`).",
      "format": "uint",
      "minimum": 1,
      "type": "integer"
    },
    "max_bytes": {
      "default": 32768,
      "description": "The most bytes a `unified` page's files take, as the JSON array `files` they print as: at\nleast 1 (0 is `E_INVALID_ARG`). The page stops before the first file that would take it\npast this, but always holds one file, whose hunks are cut to the first ones that fit\n(`hunks_truncated`) when they alone would pass it. A `names` or `stat` page is held by\n`limit` alone.",
      "format": "uint64",
      "minimum": 1,
      "type": "integer"
    },
    "paths": {
      "description": "Only the files at or below these repository paths (a file's path takes that file; one\ntrailing `/` is taken); every file when empty or omitted.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "to": {
      "description": "The revision to diff to: the new side. A revision as the caller wrote it, for the store to resolve: a ref name (`main`,\n`release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits,\noptionally followed by `~N` for the N-th first-parent ancestor.",
      "type": "string"
    }
  },
  "required": [
    "from",
    "to"
  ],
  "title": "DiffReq",
  "type": "object"
}

Annotations#

It only reads the store.

Annotation	Value	Meaning
`destructiveHint`	`false`	True: a tool that changes the store may overwrite or delete what is there, not only add to it.
`idempotentHint`	`true`	True: calling it again with the same arguments changes nothing more.
`openWorldHint`	`false`	True: it reaches beyond a closed set of things. Every tool here stays inside the store.
`readOnlyHint`	`true`	True: the tool does not change its environment, the store.

Its entry in tools/list carries no _meta.

CLI command#

swarmops diff runs the same operation and prints the same envelope.

Examples#

{
  "id": 16,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "format": "stat",
      "from": "[c1]",
      "to": "main"
    },
    "name": "diff"
  }
}

{
  "id": 16,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "{\"ok\":true,\"op\":\"diff\",\"api\":1,\"result\":{\"from\":\"[c1]\",\"to\":\"[landed]\",\"files\":[{\"path\":\"docs.md\",\"status\":\"added\",\"binary\":false,\"insertions\":1,\"deletions\":0},{\"path\":\"src/lib.rs\",\"status\":\"modified\",\"binary\":false,\"insertions\":1,\"deletions\":1}],\"truncated\":false},\"meta\":{\"repo\":\"[tmp]/store\",\"elapsed_ms\":\"[elapsed_ms]\",\"resolved\":{\"[c1]\":\"[c1]\",\"main\":\"[landed]\"},\"auth\":\"trust\"}}",
        "type": "text"
      }
    ],
    "isError": false,
    "structuredContent": {
      "api": 1,
      "meta": {
        "auth": "trust",
        "elapsed_ms": "[elapsed_ms]",
        "repo": "[tmp]/store",
        "resolved": {
          "[c1]": "[c1]",
          "main": "[landed]"
        }
      },
      "ok": true,
      "op": "diff",
      "result": {
        "files": [
          {
            "binary": false,
            "deletions": 0,
            "insertions": 1,
            "path": "docs.md",
            "status": "added"
          },
          {
            "binary": false,
            "deletions": 1,
            "insertions": 1,
            "path": "src/lib.rs",
            "status": "modified"
          }
        ],
        "from": "[c1]",
        "to": "[landed]",
        "truncated": false
      }
    }
  }
}

The server ran as swarmops mcp --repo [tmp]/store --as agent/worker-17, after initialize. Recorded by the MCP 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, the version.

Details#

format picks how much each differing file carries: names (the default) its path and status, stat also its line counts, unified also its hunks. Pass a limit of 100 or less, keep max_bytes at 32768 or less for unified, and page on with the cursor. Files come in path order.

Return information#

A tool result: the envelope, whose op is diff, as structuredContent and again as the text of its one content block. isError is true exactly when the envelope's ok is false. On success the envelope's result is what swarmops diff returns.

Errors#

A failed call is a tool result with isError: true; the envelope's error.code is one of the error codes.

E_INVALID_ARG: arguments that do not fit DiffReq, a field named twice among them included, or that break one of the server's own rules.
E_NOT_A_REPO: the server's store is not there; the server serves on.
E_INTERNAL: the operation panicked, a bug.

Then the errors of the operation, as swarmops diff lists them.