sync#

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

Fetches a git remote, lands main's unpublished changes onto its head (those the remote holds already are dropped), moves main there and pushes it; with mode local it pushes nothing. A conflict is E_CONFLICT with the report a land gives, and nothing moves.

Metadata

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

Input schema#

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

Field	Type	Required	Default	Description
`max_attempts`	integer	no	`8`	How many times to fetch and land again when the remote or `main` moved meanwhile: 1 to 32.
`mode`	string	no	`"publish"`	`publish` (the default) pushes; `local` stops before the push. Whether `sync` sends what it landed.
`remote`	string	yes		The remote, by its 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": "`sync`: fetch a remote, land `main`'s unpublished changes onto the remote's head, move\n`main` there and push it. It moves `main`, so it needs an identity.",
  "properties": {
    "max_attempts": {
      "default": 8,
      "description": "How many times to fetch and land again when the remote or `main` moved meanwhile: 1 to\n32.",
      "format": "uint32",
      "maximum": 32,
      "minimum": 1,
      "type": "integer"
    },
    "mode": {
      "default": "publish",
      "description": "`publish` (the default) pushes; `local` stops before the push. Whether `sync` sends what it landed.",
      "oneOf": [
        {
          "const": "publish",
          "description": "Land onto the remote's head, move `main`, and push it.",
          "type": "string"
        },
        {
          "const": "local",
          "description": "The same without the push: for a branch that takes pull requests only.",
          "type": "string"
        }
      ]
    },
    "remote": {
      "description": "The remote, by its name.",
      "type": "string"
    }
  },
  "required": [
    "remote"
  ],
  "title": "SyncReq",
  "type": "object"
}

Annotations#

It lands main's unpublished changes onto a git remote's head, moves main there and pushes. Run again after the remote moved, it lands again. 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`	`false`	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 sync runs the same operation and prints the same envelope.

Examples#

No recorded example yet.

Return information#

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