branch
merge
Promote one branch's changes into another as a single atomic commit.
strata branch mergedb.branches.merge(source: 'str', target: 'str', *, strategy: 'Any' = 'strict') -> 'Any'wire branch_merge
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.
To see the complete help for this command, run:
strata branch merge --helphelp(db.branches.merge)
Example
Promote a fork's change back into the branch it came from.
strata kv put config basestrata branch fork default experimentstrata command run --command-json '{"branch":"experiment","key":"Y29uZmln","type":"kv_put","value":"dHVuZWQ="}' # change on the forkstrata branch merge experiment default --strategy strict # applies the fork's change onto default
_ = 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. |
| target | string | yes | The branch that receives the promotion. |
| strategy | PromotionStrategy | no | Conflict-resolution strategy (`strict` refuses on conflict).one of: strict, source_wins |
Returns
MutationAck<PromotionOutcomeItem>
- dataPromotionOutcomeItem
- typestring
Errors
Recover by code. Retry policy and commit outcome come from the shipped error registry.
| Code | Retry | Commit outcome |
|---|---|---|
| failed_precondition.engine.runtime_closed | never | not_started |
| not_found.engine.branch | never | not_applicable |
| invalid_argument.engine.branch_name | never | not_started |
| invalid_argument.engine.branch_name_reserved | never | not_started |
| conflict.engine.promotion | never | not_started |
| invalid_argument.engine.branch_point | never | not_started |