Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Branch and merge

Create a branch to isolate a schema change, then merge it back through panproto’s schema-aware merge operation.

Prerequisites

A panproto repository with at least one commit (Init and commit).

The task

schema branch feature/add-handle
schema checkout feature/add-handle
# edit the schema, add a `handle` field
schema add user.json
schema commit -m "add handle"

schema checkout main
schema merge feature/add-handle

merge uses the current commit, the named branch, and their common ancestor. A fast-forward moves the current branch. A divergent merge performs a three-way structural merge and records a two-parent commit unless --no-commit or --squash changes that behavior. Before it records a normal clean merge commit, the repository verifies that the total migrations from the base through both parents to the result form a commuting cocone. When both branches add the same name with the same definition, structural merge identifies the additions. In that case the result is not a free pushout. The --no-commit and --squash paths do not run this commit-time cocone check.

If both branches make incompatible changes to the same structure, the command prints the detected conflicts and exits nonzero. The current CLI does not persist an editable conflict descriptor.

Resolve the source schemas on one branch, commit that resolution, and rerun the merge:

schema checkout feature/add-handle
# edit user.json to incorporate the intended result
schema add user.json
schema commit -m "resolve merge inputs"
schema checkout main
schema merge feature/add-handle

Verification

schema log

shows a Merge: line for a two-parent merge commit. The --graph option is accepted but currently ignored by the renderer.

Common mistakes

  • Expecting checkout to rewrite source files. It moves the repository ref only. Edit or regenerate working files explicitly.
  • Looking for a saved conflict object after a failed merge. Capture the printed conflict details; the CLI does not yet provide an interactive continuation flow.

See also