gc#

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

Removes the store's leftovers (temp files past a day, a crashed create's staging, derived values of older versions, what an upgrade left) and never an object or a changeset; dry_run lists them only. E_MAINTENANCE_BUSY while another gc, repair or upgrade runs: retry.

Metadata

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

Input schema#

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

Field	Type	Required	Default	Description
`dry_run`	boolean	no	`false`	List what it would remove, and remove nothing.

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": "`gc`: remove the store's leftovers (temp files past a day, a crashed create's staging,\nderived values of older versions, what an upgrade left of the format before). It removes no\nobject and no changeset.",
  "properties": {
    "dry_run": {
      "default": false,
      "description": "List what it would remove, and remove nothing.",
      "type": "boolean"
    }
  },
  "title": "GcReq",
  "type": "object"
}

Annotations#

It removes or rewrites store files that the journal and the objects stand for, and moves no ref and records nothing. Run again, it finds its work done.

Annotation	Value	Meaning
`destructiveHint`	`true`	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`	`false`	True: the tool does not change its environment, the store.

Its entry in tools/list carries no _meta.

CLI command#

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

Examples#

No recorded example yet.

Return information#

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

gc#