branch
preview
Preview promoting one branch into another, reporting conflicts without mutating either branch.
strata branch previewdb.branches.preview(source: 'str', target: 'str', *, strategy: 'Any' = 'strict') -> 'Any'wire branch_preview
Previews promoting the `source` branch into the `target` branch: it derives the branch point from the recorded fork lineage, runs a three-way comparison, and reports the conflicts a promotion would hit - entries both branches changed differently since the branch point. Preview is read-only: it mutates neither branch.
Each conflict reports what the selected `strategy` would do - `strict` refuses (`refused`), `source_wins` overwrites the target with the source value. A preview with no conflicts is clean and a promotion under `strict` would apply. Preview covers the capabilities a promotion applies - key-value, JSON, and vectors; events and graphs are diff-only and never appear as promotion conflicts. Branches with no shared fork lineage are rejected with `invalid_argument.engine.branch_point`.
Status commands return a scalar or compact status payload and do not mutate database state.
To see the complete help for this command, run:
strata branch preview --helphelp(db.branches.preview)
Example
Preview promoting a fork 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 preview experiment default --strategy strict # a clean preview - no conflicting changes on 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.preview("experiment", "default", strategy="strict") # a clean preview - no conflicting changes on default
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| source | string | yes | The branch whose changes would be promoted. |
| target | string | yes | The branch that would receive the promotion. |
| strategy | PromotionStrategy | no | Conflict-resolution strategy to evaluate the preview under.one of: strict, source_wins |
Returns
StatusResponse<BranchPreviewItem>
- dataBranchPreviewItem
- 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 |
| invalid_argument.engine.branch_point | never | not_started |