commit#

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "`commit`: record a changeset from an explicit change list. It moves no ref, unless\n`advance` names one.",
  "properties": {
    "advance": {
      "description": "Also move this ref (`main` or `release/<name>`) to the new changeset, in the same\ntransaction as the changeset itself, so that both are recorded or neither. The move\nhappens only if the ref still names the changeset's parent (for a root commit, only if the\nref does not exist yet): it is always a one-step fast-forward. Otherwise nothing is\nrecorded and the commit fails with `E_CAS_MISMATCH` (`details.committed: false`,\n`details.actual` what the ref names). Give as `parent` the full id the ref held when you\nread it: without `parent` the commit builds on the ref's head when it runs, so the move\ncatches a race from there on, not a change made since you read the ref (M1 has no\nmerge). `swarmops mcp` refuses `advance` without a full 64-hex `parent` (`E_INVALID_ARG`).\nA store that does not know this field ignores it and moves no ref: its response has no\n`advanced`.",
      "type": [
        "string",
        "null"
      ]
    },
    "allow_empty": {
      "default": false,
      "description": "Record the changeset even if it changes nothing.",
      "type": "boolean"
    },
    "changes": {
      "description": "What to change, relative to the parent. The contents hold at most 1 GiB together, by the\nsizes they declare (inline text's length, the bytes base64 decodes to, a client file's\nlength; a `blob` named by id counts nothing): more is `E_TOO_LARGE` with `scope`\n`commit`, refused before any content is read. Store large contents with `blob_put` first,\nand name them by id.",
      "items": {
        "description": "One change of a commit.",
        "properties": {
          "content": {
            "anyOf": [
              {
                "description": "A `put`'s content, as an object with one key.",
                "oneOf": [
                  {
                    "additionalProperties": false,
                    "description": "UTF-8 text, verbatim.",
                    "properties": {
                      "inline": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "inline"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "description": "Bytes in standard, padded base64.",
                    "properties": {
                      "base64": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "base64"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "description": "A blob the store holds already, by its id (64 hex digits), as `blob_put` returns it: the\ncommit neither sends nor reads its bytes. An id the store holds no blob under (none, or\na tree's or a changeset's) is `E_INVALID_ARG`, and nothing is written. `blob_put` takes\nthe other forms only.",
                    "properties": {
                      "blob": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "blob"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "description": "A file on the client's machine. The client reads it and sends its bytes, so the store is\nnever asked to read a path.",
                    "properties": {
                      "file": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "file"
                    ],
                    "type": "object"
                  }
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "The new content, at most 512 MiB (more is `E_TOO_LARGE` with `scope` `put`); a `put` needs\nit, a `delete` takes none."
          },
          "mode": {
            "anyOf": [
              {
                "description": "The kind of entry a `put` writes.",
                "oneOf": [
                  {
                    "const": "file",
                    "description": "A regular file (git mode 100644).",
                    "type": "string"
                  },
                  {
                    "const": "exec",
                    "description": "An executable file (git mode 100755).",
                    "type": "string"
                  },
                  {
                    "const": "symlink",
                    "description": "A symlink; the content is the link's target.",
                    "type": "string"
                  }
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "The kind of entry a `put` writes; `file` when omitted."
          },
          "op": {
            "description": "Whether to write the path or remove it. What a change does to its path, in a commit's change list and a changeset's changes alike.",
            "oneOf": [
              {
                "const": "put",
                "description": "Write the content at the path, creating or replacing the entry.",
                "type": "string"
              },
              {
                "const": "delete",
                "description": "Remove the path.",
                "type": "string"
              }
            ]
          },
          "path": {
            "description": "The repository path: `/`-separated, relative to the root.",
            "type": "string"
          }
        },
        "required": [
          "path",
          "op"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "idempotency_key": {
      "description": "Makes a retry of this commit safe: a uuid v7 (anything else is `E_INVALID_ARG`). The\ncommit takes the key's time, to the second, as its signature time and records the key as\n`commit_key` metadata, so the same request on the same parent makes the same changeset,\nwhich the store holds already: the response says `replayed`, and nothing is written.\nWith `advance`, a ref whose head carries the key is a replay too. Give `parent` by its full\nid: without it, a retry after the head moved commits again, on the new head.",
      "type": [
        "string",
        "null"
      ]
    },
    "message": {
      "description": "The commit message.",
      "type": "string"
    },
    "parent": {
      "anyOf": [
        {
          "description": "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"
        },
        {
          "type": "null"
        }
      ],
      "description": "The changeset to commit on top of. An explicit `parent` always wins; when it is omitted,\nthe current head of the ref `advance` names is used, else of `main`, if that ref exists,\nand otherwise the commit is a root commit. `null` is the same as omitting it. Once `main`\nexists, a root commit needs an `advance` naming a ref that does not exist yet (a known M1\nlimitation)."
    }
  },
  "required": [
    "changes",
    "message"
  ],
  "title": "CommitReq",
  "type": "object"
}