# Compare branches

Source: https://stratadb.org/docs/reference/branch/diff

Compare two branches and report the entities that differ across every primitive.

| | |
|---|---|
| Command | `branch.diff` |
| CLI | `strata branch diff` |
| Wire type | `branch_diff` |
| Python | `db.branches.diff(branch_a: 'str', branch_b: 'str', *, as_of: 'Optional[int]' = None) -> 'Any'` |
| Access | read |
| Commit | no commit |
| Wire status | stable |

Compares two branches and reports the authored entities that differ, grouped by
capability and space: entries `added` on `branch_b`, `removed` relative to
`branch_a`, and `modified` on both sides. The comparison is directional from
`branch_a` to `branch_b`.

Every data primitive is compared - key-value, JSON documents, vectors, event
streams, and graphs. Graph changes are reported per row class: nodes, edges, and
ontology appear as separate capabilities in the result. Derived rows (search and
vector indexes, graph reverse maps) are omitted. A missing branch is rejected
with `not_found.engine.branch`.

Status commands return a scalar or compact status payload and do not mutate database state.

## Examples

Compare a fork against the branch it came from, across primitives.

### CLI

```console
$ strata vector collection create notes 2 --metric cosine
$ strata kv put config base
$ strata branch fork default experiment
$ strata command run --command-json '{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}'  # diverge the key-value entry on the fork
$ strata command run --command-json '{"branch":"experiment","collection":"notes","key":"n1","type":"vector_upsert","vector":[0.1,0.2]}'  # add a vector on the fork
$ strata branch diff default experiment  # reports the key-value change and the new vector, grouped by capability
```

### Wire

```json
{"collection":"notes","dimension":2,"metric":"cosine","type":"vector_create_collection"}
{"key":"Y29uZmln","type":"kv_put","value":"YmFzZQ=="}
{"branch":"experiment","source":"default","type":"branch_fork_current"}
{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}
{"branch":"experiment","collection":"notes","key":"n1","type":"vector_upsert","vector":[0.1,0.2]}
{"branch_a":"default","branch_b":"experiment","type":"branch_diff"}
```

### Python

```python
_ = db.vectors.create_collection("notes", 2, metric="cosine")
_ = db.kv.put("config", "base")
_ = db.branches.fork("default", "experiment")
_ = db.at(branch="experiment").kv.put("config", "tuned")  # diverge the key-value entry on the fork
_ = db.at(branch="experiment").vectors.upsert("notes", "n1", [0.1, 0.2])  # add a vector on the fork
_ = db.branches.diff("default", "experiment")  # reports the key-value change and the new vector, grouped by capability
```

## Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `at_timestamp` | `integer or null` | no | Optional read-as-of commit timestamp: compare each branch as of the
`timestamp` from `history` output (a commit-timeline position, not
the `version`). |
| `branch_a` | `string` | yes | The first branch (the `A` side). |
| `branch_b` | `string` | yes | The second branch (the `B` side). |

## Returns

`StatusResponse<BranchComparisonItem>`

- `data` (`BranchComparisonItem`)
- `type` (`string`)

## Errors

Recover by code, never by message.

| Code | Retry | Commit outcome |
|---|---|---|
| [`failed_precondition.engine.runtime_closed`](https://stratadb.org/e/failed_precondition.engine.runtime_closed) | never | not_started |
| [`not_found.engine.branch`](https://stratadb.org/e/not_found.engine.branch) | never | not_applicable |
| [`invalid_argument.engine.branch_name`](https://stratadb.org/e/invalid_argument.engine.branch_name) | never | not_started |
| [`invalid_argument.engine.branch_name_reserved`](https://stratadb.org/e/invalid_argument.engine.branch_name_reserved) | never | not_started |

## Related

- [Create empty branch](https://stratadb.org/docs/reference/branch/create)
- [Delete branch](https://stratadb.org/docs/reference/branch/delete)
- [Fork branch from current head](https://stratadb.org/docs/reference/branch/fork)
- [Fork branch at timestamp](https://stratadb.org/docs/reference/branch/fork_at_timestamp)
- [Fork branch at version](https://stratadb.org/docs/reference/branch/fork_at_version)
- [Read one branch](https://stratadb.org/docs/reference/branch/get)
- [List branches](https://stratadb.org/docs/reference/branch/list)
- [Promote branch](https://stratadb.org/docs/reference/branch/merge)
- [Preview branch promotion](https://stratadb.org/docs/reference/branch/preview)