# swarmops rebase

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

Merge a change three-way onto a ref's head and record the result there as one changeset, moving no ref.

The change is HEAD with its first-parent chain since the base, merged as land merges it; the new changeset's parent is the ref's head, and the ref stays where it is. Build and test that changeset, then land it with --expect-target set to the head it was rebased onto: the landed tree is then the tested one. A conflict is E\_CONFLICT (exit 3), as a land's, and nothing is recorded.

```yaml
title: "swarmops rebase"
description: "Merge a change three-way onto a ref's head and record the result there as one changeset, moving no ref."
group: "write"
since: "0.3.0"
mutates: true
identity_required: true
mcp_tool: "rebase"
envelope_op: "rebase"
exit_codes: [0]
errors: []
syntax: "swarmops rebase [OPTIONS] <HEAD>"
```

## Syntax

```text
swarmops rebase [OPTIONS] <HEAD>
```

## Required arguments

### `HEAD`

Syntax: `<HEAD>`.

The changeset to rebase: the change's head.

## Optional arguments

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

### `--base`

Syntax: `--base <REV>`.

Where the change starts: a first-parent ancestor of HEAD (default: the merge base of HEAD and the ref's head, along first parents).

### `--onto`

Syntax: `--onto <REF>`.
Default: `main`.

The ref to rebase onto: main or release/&lt;name&gt;, and in a FORMAT 2 store a branch (feature/x) or a tag (tags/v1).

### `--message`

Syntax: `-m, --message <MSG>`.

The new changeset's message (default: HEAD's).

### `--key`

Syntax: `--key <UUID>`.

A uuid v7 that makes a retry safe: the same rebase onto the same head replays (status: replayed).

### `--max-conflict-bytes`

Syntax: `--max-conflict-bytes <N>`.
Default: `32768`.

The most bytes of hunk text an E\_CONFLICT report carries, as land's.

### `--resolve`

Syntax: `--resolve <FILE>`.

Resolve the conflicts an E\_CONFLICT report named, without a checkout: resolutions as a JSON object in FILE, or - for stdin, at most 64 MiB (swarmops schema ResolutionsInput).

{"against": THEIRS, "files": {PATH: RESOLUTION, ...}}: THEIRS is the report's theirs, by its full id, and each RESOLUTION one of {"take": "ours"}, {"take": "theirs"}, {"content": CONTENT} with an optional "mode" (CONTENT as a commit's change gives it: inline, base64, a file, or a stored blob by id) and {"delete": true}. A resolution decides its path and every path below it; the rest of the merge stands.

A resolution applies while the ref holds its path as THEIRS did, whether the path conflicts or not. A path the ref changed since is stale: the land fails with E\_CONFLICT again, its report naming the path in stale, as it does for each conflict left unresolved. Read the report's theirs, and resolve against it.

## Examples

### CLI

No recorded example yet.

### MCP

No recorded example yet.

## Return information

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `auto_merged` | `array of string` | no | The paths both sides changed whose contents merged cleanly into a content neither side had. Omitted when empty. |
| `base` | `string` | yes | The changeset the change was taken from. |
| `changeset` | `string` | yes | The changeset that holds the result: the recorded one, `head` when it is up to date, the ref's head when the change was absorbed. |
| `files_changed` | `integer` | yes | How many paths `changeset` changes against `onto`. |
| `onto` | `string` | yes | The ref's head the change was merged onto: `changeset`'s parent when one was recorded. |
| `root` | `string` | yes | The root tree of `changeset`. |
| `status` | `RebaseStatus` | yes | How the rebase ended. |

Envelope `op`: `rebase`.

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 commit`](commit.md)
- [`swarmops land`](land.md)
- [`swarmops land-check`](land-check.md)
- [`swarmops land-group`](land-group.md)
- [`swarmops revert`](revert.md)
- [`swarmops blob put`](blob-put.md)
- [`swarmops blob has`](blob-has.md)
- [CLI reference](../cli.md)
- [Error codes](../errors.md)