push#

Describes v0.11.0Last changed 2026-10-22View as Markdown

Sends a store ref (main by default) to a git remote's branch by compare-and-swap, never by force: the remote moves only from what the last fetch saw. A remote that moved since is E_REMOTE_DIVERGED and nothing is sent: fetch or sync, then push again. Run again, it sends nothing.

Metadata

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

Input schema#

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

Field	Type	Required	Default	Description
`branch`	string or null	no		The remote branch; by default the remote's followed branch for `main`, and the same name for `release/<name>`.
`remote`	string	yes		The remote, by its name.
`source_ref`	string	no	`"main"`	The store ref to send: `main` (the default) or `release/<name>`.

JSON Schema#

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

JSON

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "`push`: send a store ref to a remote branch by compare-and-swap, never forcing: the remote\nmoves only from the head the last fetch saw to a descendant of it. A push is an export, so\nit needs no identity.",
  "properties": {
    "branch": {
      "description": "The remote branch; by default the remote's followed branch for `main`, and the same\nname for `release/<name>`.",
      "type": [
        "string",
        "null"
      ]
    },
    "remote": {
      "description": "The remote, by its name.",
      "type": "string"
    },
    "source_ref": {
      "default": "main",
      "description": "The store ref to send: `main` (the default) or `release/<name>`.",
      "type": "string"
    }
  },
  "required": [
    "remote"
  ],
  "title": "PushReq",
  "type": "object"
}

Annotations#

It moves history between the store and a git remote, and moves no ref of the store: a push moves the remote's branch only from what the last fetch saw, to a descendant of it. Run again, it fetches or sends nothing new. It reaches the remote, beyond 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`	`true`	True: it reaches beyond a closed set of things. Every tool here stays inside the store.
`readOnlyHint`	`false`	True: the tool does not change its environment, the store.

Its entry in tools/list carries no _meta.

CLI command#

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

Examples#

No recorded example yet.

Return information#

A tool result: the envelope, whose op is push, 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 push 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 PushReq, 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 push lists them.