# Merging Branches

Source: https://www.omnigraph.dev/docs/branching/merge

A merge integrates one branch into another and publishes the target change
atomically across the whole graph.

```bash
omnigraph branch merge review/2026-04-25 --into main \
  --target ./graph.omni
```

The source is positional. `--into` defaults to `main`.

The same merge as a GQ statement, sent to `POST /mutate` with no request
target, name, or parameters:

```text
branch merge "review/2026-04-25" into main
```

`into` defaults to `main`; a name with `/`, `-`, or `.` is quoted, a bare
identifier such as `main` is not. The answer is a `ChangeOutput` with
`outcome.kind = "merged"` and `outcome.merge` one of `already_up_to_date`,
`fast_forward`, or `merged`; after a `fast_forward` or `merged` result,
`commit` identifies that merge's own publication, even if another writer has
since advanced the target. The statement has no `--delete-branch`
composition: follow it with `branch delete <source>`. A merge statement takes
no commit precondition -- `POST /mutate/if-graph-commit` and `--if-commit`
refuse one beside it -- and no front offers a conditional merge today.

A merge preserves changes already integrated into a branch when you later
merge that branch back. For example, after merging a new edge from `main`
into `review`, editing only a node on `review` and merging it into `main`
preserves that edge. A merge whose source and target tables reached the same
version count on different branches fast-forwards; earlier releases refused
it with a `table version … already exists` error.

## Outcomes

* **Already up to date**: the target already contains the source changes.
* **Fast-forward**: the target still has the merge base's schema and table
  versions, so it takes the source's state. The check reads state, not
  history: a target merged again from a branch it fast-forwarded before, with
  no write in between, fast-forwards again. One exception: when a
  fast-forward into `main` carried a table whose changes cancel out on the
  branch, or a table on a fork left by a branch created before storage format
  v11, `main` ends on its own version of that table, so a later merge from
  that branch can report **Merged**. The merged data is the same.
* **Merged**: both branches changed, so OmniGraph performs a three-way,
  entity-level merge and creates a commit with two parents.

`branch merge --json`, the HTTP merge route and the GQ merge statement all
return `commit` with the exact commit id, manifest version, parents, branch,
actor and creation timestamp (Unix microseconds). Fast-forward returns the new
target commit; its merged parent identifies the source head. An already-up-to-date
merge publishes nothing and returns `commit: null`.

If a remote response is lost or incomplete, the merge may have committed. The
CLI does not resubmit it automatically. Inspect the intended target changes and
relevant history before deciding what to do next; a later head alone cannot
identify the missing merge receipt.

When only the source changed a table since the merge base, a merge into a
named branch can adopt that exact table snapshot without copying its rows.
This also works when the target already has its own table history. Tables
changed on both sides still use the normal three-way merge and constraint
checks.

The target can continue writing after adoption. Other live branches keep their
current table snapshots through those target writes and cleanup;
creating a replacement branch is unnecessary. Cleanup retains the underlying
histories they still need. Avoiding a table copy does not eliminate the reads
needed to validate a merge.

The source branch is unchanged by the merge. Use `--delete-branch` for the
normal review-branch lifecycle:

```bash
omnigraph branch merge review/2026-04-25 --into main --delete-branch \
  --target ./graph.omni
```

Deletion happens after a successful merge and has its own authorization check.
If deletion is denied or the source still has descendants, the merge remains
successful and durable. The CLI exits 0 and warns in human output; HTTP and CLI
JSON preserve `commit`, report `branch_deleted: false` and include the structured
`branch_delete_error_details` (`error`, plus typed `code` and details where available).
Successful deletion reports `branch_deleted: true`; without `--delete-branch`,
both deletion fields are absent. v0.12 removes the old `branch_delete_error`
string. Inspect and retry deletion separately; do not replay a successful merge.

Deleting a branch is irreversible and may make branch-only commits unavailable.
It also releases old history for a later cleanup.

## Preview a merge

```bash
omnigraph branch merge feature --into main --dry-run --target ./graph.omni --json
```

A dry run runs the merge through classification and constraint validation,
then stops. It reports the outcome the merge would have now, or fails with the
same structured conflict list, and writes nothing: `commit` is `null` and
`dry_run` is `true`. It is a read of both branches, so it needs `read` on each
and no `branch_merge` grant. It refuses `--as-commit` and `--delete-branch`.
Over HTTP, send `dry_run: true` to `POST /graphs/{graph_id}/branches/merge`.
The GQ statement `branch merge feature into main dry run` is the same read at
`POST /query`: it answers one row with `source`, `target` and `outcome`, and a
conflict is the 409 a merge answers.

A dry run answers whether the merge would succeed. To see what it would change,
use [`branch diff`](https://www.omnigraph.dev/docs/branching/changes.md#review-a-branch). To review the exact result
before it lands, merge `--as-commit` and inspect the proposal with
`commit changes`; the proposal expires once the target branch moves.

## Conflicts

When both sides changed the same logical data incompatibly, the merge returns a
structured conflict list and publishes nothing.

| Kind                         | Meaning                                                             |
| ---------------------------- | ------------------------------------------------------------------- |
| `divergent_insert`           | Both branches inserted the same id.                                 |
| `divergent_update`           | Both branches updated the same entity differently.                  |
| `delete_vs_update`           | One branch deleted an entity the other updated.                     |
| `orphan_edge`                | The result would contain an edge whose endpoint was deleted.        |
| `unique_violation`           | The result would violate uniqueness.                                |
| `cardinality_violation`      | The result would violate edge cardinality.                          |
| `value_constraint_violation` | The result would violate an enum, range, or other value constraint. |

A merge classifies both sides against their merge base, the newest commit
both branches descend from, counting a merged branch as an ancestor: a
commit both branches descend from that no other such commit descends from.
When two such commits are each not an ancestor of the other, the base is the
one nearest the two heads (the fewest commits between it and the heads,
summed), then the one with the higher generation (its distance from the
first commit along the longest path), then the one with the smaller commit
id. Two branches that
each merged the same third branch therefore share that branch's commit as
their base, and an entity only one of them changed after that import merges
cleanly. The record of such a commit lives in the branch
it was merged from, and the merge can read it from a live branch or retained
retired history. Cleanup preserves the exact selected base and the retired
histories needed to resolve it. Recreating the logical branch name cannot
substitute the replacement branch's same-numbered snapshot.

Each conflict identifies the affected type and, when applicable, entity id. The
HTTP server returns conflicts with status `409`, the same answer for
`POST /branches/merge` and for a `branch merge` statement on `POST /mutate`.
Reconcile the data on one or both branches, then run the merge again.

### Edges inserted on both sides

Whether the same edge added on both branches converges depends on the edge
type's declared identity:

* No declaration: edge ids are generated, so each side's insert is its own
  row and the merge keeps both. This is the documented multiset default;
  parallel edges are legitimate data.
* `@unique(@src, @dst)`: each branch's write succeeds on its own, and the
  merge reports `unique_violation`. Releases before edge keys provide this
  guard as `@unique(src, dst)`; from 0.11 it is spelled
  `@unique(@src, @dst)`.
* `@key(@src, @dst)`: both sides derive the same id, so identical inserts
  converge to one row with no conflict. If the sides disagree on a non-key
  property, the merge reports `divergent_insert` on the edge type with the
  derived id as the entity id (for `@key(@src, @dst)` a JSON array such as
  `["Alice","Bob"]`; the elements are the endpoint node ids, so they are
  generated ids when the endpoint type declares no key). Reconcile it like any divergent insert: align the
  property on one branch (insert the same key again with the agreed
  values; the insert upserts), then merge again.

## Merge classification mode

The `merge_lineage` [session setting](https://www.omnigraph.dev/docs/queries-search/queries.md#session-settings)
(`request` scope; `set merge_lineage = off;` before the statement, `--set
merge_lineage=off`, or the request's `settings` field; process default
`OMNIGRAPH_MERGE_LINEAGE`) selects how a branch merge finds what changed. `on`
(the release default) discovers candidates from Lance version metadata —
fragment lists and deletion files — and compares candidate rows, for tables
both branches changed and for tables only the source changed (including a
fast forward), so its cost follows what changed rather than the table size. Known deleted
row positions use bounded direct reads. Candidate filtering may still scan data
when an applicable index is absent; a fail-closed
precondition gate falls back to the full three-way scan whenever any
assumption cannot be proven (Blob-bearing schema, differing schemas or storage
paths across the pins, version pins not matching the manifest entries, missing
stable identifiers or the exact-id primary-key contract, or a candidate set
past its byte budget). The table version a side pins need not descend from
the one the merge base pins, so merging a branch back after an earlier merge
still qualifies. `off` forces the full three-way scan everywhere — the
operational fallback if merge results are ever in question.
`verify` runs both, compares their decisions entity by entity, publishes the
scan's result, and fails the merge loudly on any divergence (the debug-build
default, used for validation; it costs both paths). A merge that succeeds
produces the same result in every mode; only cost differs. An unrecognized
value is refused where it arrives: in the environment it refuses startup, in
a request or a file it refuses that request.

Later writes create fresh table storage when needed and leave unused former
storage for explicit cleanup. They do not reclaim a previous table history as
part of preparing the write or merge.

## Validation limit

Before it publishes, a merge checks the target's constraints (value and enum
checks, uniqueness, edge endpoints and `@card`) against its delta: every row
the merge adds or changes since the merge base, and every id it removes. It
reads the delta from storage one batch at a time. A value that only a
single-row check reads, such as a long description or a property under
`@range`, is checked in its batch and then released, and vectors and Blob
payloads are not read at all. What the merge keeps until the checks finish
is the delta's keys: entity ids, the values of each `@key` and `@unique`
group, an edge's endpoints when they or its `@card` are checked, and the
removed ids.

Those keys are limited to 32 MiB per merge, counted as the bytes of their
values (a string's length, plus 4 bytes; a null counts nothing), whatever
buffers storage returned them in. The checks hold each key in lookup tables of
their own, so their memory is several times this count, not bounded by it.
The limit is fixed: `write_max_bytes` and `query_memory_bytes` do not change
it. The check sets no bound of its own on a row's width. A merge that writes
rows (for a table both branches changed) keeps its own `write_max_bytes`
allowance, as any write does, so a row wider than 32 MiB, written under a
raised value, needs that value again; a merge that adopts the source's table
by pointer writes no row.
It applies to the whole delta since the merge base, however the source's
commits were chunked, so a branch whose every load fit its own bounds can
still reach it. A merge past the limit publishes nothing and fails with
`resource limit exceeded for branch-merge retained validation key bytes`
(over HTTP, `413` with a `resource_limit` detail naming the resource, its
limit and the actual bytes; disposition `effects: none`, `action: fix`).

Merge such a branch in stages, each holding part of its commits:

1. List the source's commits and pick one partway along it:
   `omnigraph commit list --branch <source> --target ./graph.omni`.
2. Start a branch at that commit:
   `omnigraph branch create <stage> --from-commit <commit-id> --target ./graph.omni`.
3. Merge `<stage>`, then merge the source. The first merge records the
   commit as part of the target's history, so it becomes the base of the
   second merge, whose delta holds only the later commits.

Use more stages if a part is still past the limit. A single commit whose own
keys pass the limit cannot be split this way; write that change again as
smaller commits. A fast-forward whose tables only gain nodes of types with no
`@unique`, `@range`, `@check` or enum property, and no edge type with a
`@card` minimum from them, needs no check and has no such limit.

## After a large merge

Indexes do not define merge correctness. Newly merged entities remain queryable even
when index coverage has not caught up, but some searches may scan them. Run
`omnigraph optimize` after a large merge to restore efficient layout and index
coverage.

A merge that writes rows is also bounded by the Blob payload it copies; see
[Blob limits](https://www.omnigraph.dev/docs/schema/blobs.md#limits).

See [Branches, Commits, and History](https://www.omnigraph.dev/docs/branching.md) for the complete branch workflow.