branch

The branch subcommand manages branches in an Omnigraph repository. 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	Path to the Omnigraph repository
`--from`	yes	Source branch to fork from

Examples

Create a branch from main:

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

Create a branch from another branch:

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

branch list

List all branches and their current snapshot versions.

Usage

omnigraph branch list --uri <path>

Example

omnigraph branch list --uri ./repo.omni

BRANCH              SNAPSHOT
main                5
feature-x           7
enrichment-run-42   7

Add --json for structured output:

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

{
  "branches": [
    { "name": "main", "snapshot_version": 5 },
    { "name": "feature-x", "snapshot_version": 7 },
    { "name": "enrichment-run-42", "snapshot_version": 7 }
  ]
}

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	Path to the Omnigraph repository
`--into`	yes	Target branch to merge into
`--json`	no	Output result as JSON

Outcomes

Outcome	Meaning
`fast_forward`	Target has no changes since the fork point. Pointer moves forward.
`merged`	Both branches diverged. Three-way merge produces a new snapshot.
`already_up_to_date`	Target already contains all source changes.

Example

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

{
  "outcome": "merged",
  "source": "feature-x",
  "target": "main",
  "new_snapshot_version": 8
}

If conflicts are detected, the merge fails and the response includes the conflict details:

{
  "outcome": "conflict",
  "conflicts": [
    {
      "table": "Person",
      "key": "alice",
      "type": "divergent_update",
      "property": "age",
      "source_value": 33,
      "target_value": 34
    }
  ]
}

Typical workflow

A complete branch workflow from creation to merge:

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

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

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

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

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

branch

On this page