# Promote branch

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

Promote one branch's changes into another as a single atomic commit.

| | |
|---|---|
| Command | `branch.merge` |
| CLI | `strata branch merge` |
| Wire type | `branch_merge` |
| Python | `db.branches.merge(source: 'str', target: 'str', *, strategy: 'Any' = 'strict') -> 'Any'` |
| Access | write |
| Commit | commits on success |
| Wire status | stable |

Promotes the `source` branch's changes into the `target` branch as a single
atomic commit, leaving the source unchanged. The branch point is derived from
the recorded fork lineage, and a three-way merge applies every change the source
made since that point.

Merge applies to key-value, JSON, and vector data. Event streams and graphs are
compared (see `branch.diff`) but never merged - divergent append-only and
structural data cannot be three-way merged - so a promotion leaves them
untouched.

The `strict` strategy (the default) refuses with `conflict.engine.promotion`,
mutating nothing, when the two branches changed the same entity differently since
the branch point. The `source_wins` strategy applies the source side's value or
tombstone for each such conflict and reports every overwritten or deleted target
entry. A promotion that applies nothing writes no commit and leaves the target
unchanged.

Branches with no shared fork lineage are rejected with
`invalid_argument.engine.branch_point`; a missing branch with
`not_found.engine.branch`.

Successful mutations return an acknowledgement of the outcome: for a state-changing write, the affected target with the mutation effect and commit facts; for mutations that produce a domain result (such as a branch or a promotion outcome), that result object.

## Examples

Promote a fork's change back into the branch it came from.

### CLI

```console
$ strata kv put config base
$ strata branch fork default experiment
$ strata command run --command-json '{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}'  # change on the fork
$ strata branch merge experiment default --strategy strict  # applies the fork's change onto default
```

### Wire

```json
{"key":"Y29uZmln","type":"kv_put","value":"YmFzZQ=="}
{"branch":"experiment","source":"default","type":"branch_fork_current"}
{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}
{"source":"experiment","strategy":"strict","target":"default","type":"branch_merge"}
```

### Python

```python
_ = db.kv.put("config", "base")
_ = db.branches.fork("default", "experiment")
_ = db.at(branch="experiment").kv.put("config", "tuned")  # change on the fork
_ = db.branches.merge("experiment", "default", strategy="strict")  # applies the fork's change onto default
```

## Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `source` | `string` | yes | The branch whose changes are promoted. |
| `strategy` | `PromotionStrategy` | no | Conflict-resolution strategy (`strict` refuses on conflict). One of: strict, source_wins. |
| `target` | `string` | yes | The branch that receives the promotion. |

## Returns

`MutationAck<PromotionOutcomeItem>`

- `data` (`PromotionOutcomeItem`)
- `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 |
| [`conflict.engine.promotion`](https://stratadb.org/e/conflict.engine.promotion) | never | not_started |
| [`invalid_argument.engine.branch_point`](https://stratadb.org/e/invalid_argument.engine.branch_point) | never | not_started |

## Related

- [Create empty branch](https://stratadb.org/docs/reference/branch/create)
- [Delete branch](https://stratadb.org/docs/reference/branch/delete)
- [Compare branches](https://stratadb.org/docs/reference/branch/diff)
- [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)
- [Preview branch promotion](https://stratadb.org/docs/reference/branch/preview)