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`	no	Source branch to fork from; defaults to `main`

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 in a repository.

Usage

omnigraph branch list --uri <path>

Example

omnigraph branch list --uri ./repo.omni

feature-x
main

Add --json for structured output:

omnigraph branch list --uri ./repo.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 ./repo.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	Path to the Omnigraph repository
`--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 ./repo.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 ./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 --uri ./repo.omni \
    --query mutations.gq \
    --name mark_completed \
    --params '{"slug": "auth"}' \
    --branch feature-x

# 4. Verify the result
omnigraph read --uri ./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