# swarmops push

> Release: 0.11.0 · Last changed: 2026-11-13 · Source: https://github.com/KeiaiLab/SwarmOps/blob/stable/docs/reference/commands/push.md

Send a store ref to a remote branch by compare-and-swap, never by force: the remote moves only from the head the last fetch saw, to a descendant of it.

The ref is exported into the store's mirror on top of what the last fetch saw of the branch, so the export only appends, then git pushes it with a lease on that value. A remote that moved since fails with E\_REMOTE\_DIVERGED (exit 3) and nothing is sent: fetch, or sync. Run again, it sends nothing and starts no git. It needs no identity: a push is an export.

```yaml
title: "swarmops push"
description: "Send a store ref to a git remote's branch by compare-and-swap, never by force."
group: "remotes"
since: "0.2.0"
mutates: true
identity_required: false
mcp_tool: "push"
envelope_op: "push"
exit_codes: [0]
errors: []
syntax: "swarmops push [OPTIONS] <REMOTE> [REF[:BRANCH]]"
```

## Syntax

```text
swarmops push [OPTIONS] <REMOTE> [REF[:BRANCH]]
```

## Required arguments

### `REMOTE`

Syntax: `<REMOTE>`.

The remote, by its name.

## Optional arguments

The command also takes the [global options](../cli.md#global-options).

### `REF[:BRANCH]`

Syntax: `<REF[:BRANCH]>`.

What to send, as &lt;ref&gt;\[:&lt;branch&gt;\]: the store ref (main, the default, release/&lt;name&gt;, or in a FORMAT 2 store a branch (feature/x), not a tag) and the remote branch (by default the remote's followed branch for main, the same name for any other ref).

## Examples

### CLI

No recorded example yet.

### MCP

No recorded example yet.

## Return information

`result` is a `PushResp` (`swarmops schema PushResp` prints its JSON Schema).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `branch` | `string` | yes | The remote branch. |
| `head_changeset` | `string` | yes | The changeset at the store ref's head. |
| `new` | `string` | yes | The commit the branch names now: the export of `head_changeset`. |
| `objects_written` | `integer` | yes | How many git objects the push's export wrote into the mirror. |
| `old` | `string or null` | no | The commit the branch named before; omitted when it did not exist. |
| `remote` | `string` | yes | The remote, by its name. |
| `rewritten` | `integer` | yes | How many of the exported commits have another id than the commit they were imported from, as `git export`'s `rewritten`. |
| `status` | `PushStatus` | yes | What the push did. |
| `warnings` | `array of string or null` | no | What the push has to say that did not stop it. Omitted when there is nothing. |

Envelope `op`: `push`.

Exit codes:

- `0`: Success.

## Errors

No golden step shows this command failing yet.

Any command that opens a store may also fail with a store error, such as [`E_NOT_A_REPO`](../errors.md#e_not_a_repo), [`E_IO`](../errors.md#e_io) or [`E_STORE_CORRUPT`](../errors.md#e_store_corrupt); a command line the grammar refuses is [`E_INVALID_ARG`](../errors.md#e_invalid_arg) (exit 2).

## See also

- [`swarmops clone`](clone.md)
- [`swarmops remote add`](remote-add.md)
- [`swarmops remote remove`](remote-remove.md)
- [`swarmops remote list`](remote-list.md)
- [`swarmops fetch`](fetch.md)
- [`swarmops sync`](sync.md)
- [`swarmops sync status`](sync-status.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)