branch

The branch subcommand manages branches in an Omnigraph graph. Branches are lightweight. Creating one does not copy data. And provide isolated workspaces for loading, mutating, and querying the graph.

branch create

Create a new branch from an existing one.

Usage

omnigraph branch create --uri <path> --from <branch> <name>

Arguments

Argument	Required	Description
`name`	yes	Name for the new branch

Options

Option	Required	Description
`--uri`	yes	Graph URI (local path or `s3://`)
`--from`	no	Source branch to fork from; defaults to `main`

Examples

Create a branch from main:

omnigraph branch create --uri ./graph.omni --from main feature-x

Create a branch from another branch:

omnigraph branch create --uri ./graph.omni --from feature-x experiment

branch list

List all branches in a graph.

Usage

omnigraph branch list --uri <path>

Example

omnigraph branch list --uri ./graph.omni

feature-x
main

Add --json for structured output:

omnigraph branch list --uri ./graph.omni --json

{
  "branches": [
    "feature-x",
    "main"
  ]
}

Use omnigraph snapshot <uri> --branch <name> if you also want the current manifest version and table state for a branch.

branch delete

Delete a branch by name.

Usage

omnigraph branch delete --uri <path> <name>

Example

omnigraph branch delete --uri ./graph.omni scratch-run

branch merge

Merge one branch into another using three-way merge.

Usage

omnigraph branch merge --uri <path> <source> --into <target>

Arguments

Argument	Required	Description
`source`	yes	Branch to merge from

Options

Option	Required	Description
`--uri`	yes	Graph URI (local path or `s3://`)
`--into`	no	Target branch to merge into; defaults to `main`
`--json`	no	Output result as JSON

Outcomes

Outcome	Meaning
`fast_forward`	Target has no changes since the fork point; the pointer moves forward
`merged`	Both branches diverged; a three-way merge produced a new target state
`already_up_to_date`	Target already contains all source changes

Example

omnigraph branch merge --uri ./graph.omni feature-x --into main --json

{
  "source": "feature-x",
  "target": "main",
  "outcome": "merged",
  "actor_id": null
}

If conflicts are detected, the merge fails and the error payload includes a merge_conflicts array:

{
  "error": "merge conflict",
  "code": "conflict",
  "merge_conflicts": [
    {
      "table_key": "node:Person",
      "row_id": "alice",
      "kind": "divergent_update",
      "message": "row changed differently on both branches"
    }
  ]
}

Typical workflow

A complete branch workflow from creation to merge:

# 1. Create a branch
omnigraph branch create --uri ./graph.omni --from main feature-x

# 2. Load data onto the branch
omnigraph load ./graph.omni --data updates.jsonl --branch feature-x

# 3. Run a mutation on the branch
omnigraph change --uri ./graph.omni \
    --query mutations.gq \
    --name mark_completed \
    --params '{"slug": "auth"}' \
    --branch feature-x

# 4. Verify the result
omnigraph read --uri ./graph.omni \
    --query queries.gq \
    --name unblocked_tasks \
    --branch feature-x \
    --json

# 5. Merge back to main
omnigraph branch merge --uri ./graph.omni feature-x --into main

branch

On this page