Schema version control basics

This tutorial uses the schema CLI to commit a TypeScript interface, create a feature branch, and merge the branch into main.

Prerequisite

Install the schema binary by following Install the CLI. The commands below create a new vcs-tutorial/ directory.

Commit the first version

Create the repository and its first source file:

mkdir -p vcs-tutorial/src
cd vcs-tutorial
schema init

cat > src/user.ts <<'EOF'
export interface User {
  name: string;
  age: number;
}
EOF

schema add src/user.ts
schema commit -m "v1 user schema"
schema log --oneline

Listing 5.1: Initializing a repository and committing a parsed TypeScript schema.

schema add parses src/user.ts through the tree-sitter registry and stages the resulting schema graph. The commit stores that graph under .panproto/. The source file remains an ordinary TypeScript file. Run schema add from the repository root so the command can find .panproto/.

Commit the rename

Replace the file with v2, inspect the staged diff, and commit it:

cat > src/user.ts <<'EOF'
export interface User {
  name: string;
  years: number;
  email: string;
}
EOF

schema add src/user.ts
schema diff --staged
schema commit -m "rename age and add email"
schema log --oneline

Listing 5.2: Staging and committing the second schema state.

The staged diff compares schema structure rather than source lines. Full-AST parsers also preserve syntax-level structure needed for source round trips, so a source edit may produce more graph changes than the two interface fields alone suggest.

Branch and merge

Create and switch to a feature branch, add handle, then merge the branch into main:

schema checkout -b feature/handle

cat > src/user.ts <<'EOF'
export interface User {
  name: string;
  years: number;
  email: string;
  handle: string;
}
EOF

schema add src/user.ts
schema commit -m "add handle"
schema checkout main
schema merge feature/handle
schema log --oneline

Listing 5.3: Creating a feature branch and merging it into main.

main has not moved since the branch was created, so this merge is a fast-forward. The command reports Merge successful. and moves the main ref to the feature commit.

There is one operational difference from git: schema checkout moves the schema-history ref but does not rewrite src/user.ts. Panproto stores and merges parsed schemas. An editor, build system, or explicit emit step remains responsible for working-source files. schema log --graph currently accepts --graph but renders the ordinary log, so the examples use --oneline.

Next

The schema version control how-to covers non-fast-forward merges, data versioning, and the git bridge. Schema version control semantics describes the three-way structural merge and its commuting-cocone check. Pushouts and merge gives the categorical comparison and its limits.