Branches

Branches are the primary unit of isolation in Omnigraph. Every graph starts with a main branch. You create additional branches to propose changes, run agent tasks, or experiment without affecting the canonical state.

Creating a branch

Create a new branch from an existing one:

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

The new branch feature-x starts at the same snapshot as main. No data is copied. The branch is a pointer that shares storage with its parent until a write causes a table to diverge.

Options

The final positional argument is the name of the new branch.

Listing branches

List all branches in a graph:

omnigraph branch list --uri ./graph.omni

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

The branch list is intentionally minimal. Use omnigraph snapshot ./graph.omni --branch <name> to inspect a branch's current manifest version and table state.

Reading from a branch

Any read command accepts a --branch flag to target a specific branch instead of the default (main):

omnigraph read --uri ./graph.omni \
    --query queries.gq \
    --name friends_of \
    --params '{"name": "Alice"}' \
    --branch feature-x

If --branch is omitted, the read runs against main.

Writing to a branch

Load and mutation commands also accept --branch:

omnigraph load ./graph.omni --data updates.jsonl --branch feature-x

omnigraph change --uri ./graph.omni \
    --query mutations.gq \
    --name mark_completed \
    --params '{"slug": "auth"}' \
    --branch feature-x

Each write advances the branch to a new snapshot. Other branches are unaffected.

Branches as transactions

Branches are the unit of atomic, reviewable work. There is no separate run or transaction lifecycle to manage from the CLI. Instead you:

1. Create a named branch (omnigraph branch create).
2. Load, mutate, or ingest data on it (omnigraph load, omnigraph change, omnigraph ingest).
3. Inspect the resulting commits (omnigraph commit list, omnigraph snapshot).
4. Merge back when ready (omnigraph branch merge), or delete the branch to discard the work (omnigraph branch delete).

Every write produces a graph commit that is recorded against the branch. The commit graph is the audit surface. There is no separate "run" record. If a mutation fails schema validation, the branch is left in its pre-mutation state and an error is returned.