ref_set#

Moves a ref, or creates one, by compare-and-swap: give create, or expected_old, the full 64-hex changeset id the ref held when you read it; a ref name or a relative revision is refused, since it is read when the call runs instead of pinning the id you read, and so is an id prefix, which stops resolving once another changeset shares it.

Input schema#

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

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": "`ref set`: move a ref, or create one, by compare-and-swap. Give exactly one of\n`expected_old` and `create`; both or neither is `E_INVALID_ARG`.",
  "properties": {
    "create": {
      "default": false,
      "description": "To create the ref. If it exists at another target, the move fails with `E_CAS_MISMATCH`;\nif it already holds `new`, nothing is written and the response is a replay\n(`already_applied`). Give this or `expected_old`, not both.",
      "type": "boolean"
    },
    "expected_old": {
      "anyOf": [
        {
          "pattern": "^[0-9a-fA-F]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "To move an existing ref: the target the caller last saw, by its full changeset id; if the\nref holds another, the move fails with `E_CAS_MISMATCH`. A ref name or a relative\nrevision is read from the store when the move runs instead of pinning the id the caller\nread: the ref's own name always matches, so the compare-and-swap protects nothing, and\n`main~1` on `main` never matches. An id prefix pins the id the caller read only until\nanother changeset shares it; then it is `E_AMBIGUOUS_ID`. `swarmops mcp` refuses all\nthree (`E_INVALID_ARG`), and the CLI's `--expect` help warns against them. Give this or\n`create`, not both."
    },
    "name": {
      "description": "The ref: `main` or `release/<name>`.",
      "type": "string"
    },
    "new": {
      "description": "The revision to point it at. 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": [
    "name",
    "new"
  ],
  "title": "RefSetReq",
  "type": "object"
}

Annotations#

It moves or deletes refs by compare-and-swap, changing what they name. Run again with the same arguments, it finds them as it asked (already_applied) or not as it expected (E_CAS_MISMATCH), and changes nothing more.

Its entry in tools/list carries no _meta.

CLI command#

swarmops ref set runs the same operation and prints the same envelope.

Examples#

{
  "id": 6,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "create": true,
      "name": "main",
      "new": "[c1]"
    },
    "name": "ref_set"
  }
}

{
  "id": 6,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "{\"ok\":true,\"op\":\"ref_set\",\"api\":1,\"result\":{\"name\":\"main\",\"new\":\"[c1]\",\"already_applied\":false},\"meta\":{\"repo\":\"[tmp]/store\",\"elapsed_ms\":\"[elapsed_ms]\",\"resolved\":{\"[c1]\":\"[c1]\"},\"auth\":\"trust\"}}",
        "type": "text"
      }
    ],
    "isError": false,
    "structuredContent": {
      "api": 1,
      "meta": {
        "auth": "trust",
        "elapsed_ms": "[elapsed_ms]",
        "repo": "[tmp]/store",
        "resolved": {
          "[c1]": "[c1]"
        }
      },
      "ok": true,
      "op": "ref_set",
      "result": {
        "already_applied": false,
        "name": "main",
        "new": "[c1]"
      }
    }
  }
}

Details#

Give create to make a new ref, or expected_old to move one: the full 64-hex changeset id the ref held when you read it, from ref_list, show, log or a commit's result. The server refuses a ref name, a relative revision such as main~1 and an id prefix there (E_INVALID_ARG): a ref name or a relative revision is read when the call runs, so the compare-and-swap would protect nothing, and a prefix stops resolving once another changeset shares it. The input schema says the same with a 64-hex pattern. The CLI's ref set --expect still takes any revision.

A ref that no longer holds expected_old is E_CAS_MISMATCH, and nothing moves: read the ref again and decide.

Return information#

A tool result: the envelope, whose op is ref_set, 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 ref set 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 RefSetReq, a field named twice among them included, or that break one of the server's own rules.
• E_IDENTITY_REQUIRED: the server runs with no identity.
• 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 ref set lists them.

See also#

• swarmops ref set
• MCP tools
• MCP integration
• Error codes