Branching

Every write to an Omnigraph repository happens on a branch. Branches let agents and humans propose changes in isolation, inspect the result, and merge back when the change is ready. Nothing touches main until you say so.

Why branching matters for agents

Agent systems that write to shared state need a way to contain mistakes. A branch gives each agent — or each step of a pipeline — its own workspace:

• Isolation — An agent can load data, run mutations, and validate results without affecting the canonical branch.
• Inspection — You can read from the branch, inspect its snapshot, and review its commit history before merging.
• Rollback — If a branch is wrong, discard it. The rest of the graph is untouched.
• Concurrency — Multiple agents can work on separate branches at the same time without coordination overhead.

How it works

Branches in Omnigraph are lightweight. Creating a branch does not copy any data. Instead, each branch is a pointer to a snapshot — a version of the graph at a specific point in time. When a write lands on a branch, only the affected tables are forked using lazy copy-on-write. Unmodified tables continue to share storage with the parent branch.

This means creating a branch is near-instant regardless of graph size, and storage grows only in proportion to what actually changed.

Key concepts

Typical workflow

A branch-based workflow follows four steps:

1. Create

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

2. Load or mutate

Write data to the branch. The rest of the graph is unaffected.

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

3. Inspect

Read from the branch to verify the result, or inspect its snapshot:

omnigraph read --uri ./repo.omni \
    --query checks.gq \
    --name validate \
    --branch feature-x

omnigraph snapshot ./repo.omni --branch feature-x

4. Merge

When the branch looks correct, merge it back:

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

Concurrency model

Omnigraph uses snapshot isolation for reads and optimistic concurrency for writes.

• Reads always see a consistent snapshot. A read on main will never see a half-applied write from another branch.
• Writes on different branches proceed independently. When two branches modify the same data and one merges first, the second merge will detect conflicts using three-way comparison against the merge base.

Writes to the same branch acquire a short-lived branch-level lock, and schema apply takes an additional schema lock on the target branch. Reads do not lock. Conflicts between branches are detected at merge time rather than during the work itself.