Version Control

Working with ops, branches, milestones, checkpoints, diff, and merge in Trellis.

The Op Stream

Every file change in a Trellis-watched directory creates an immutable op. There is no staging area — ops are generated automatically.

trellis watch
# ◉ Watching for changes...
# → src/auth.ts modified (op #48)

Branches

Branches work like Git branches, but with built-in CRDT support for concurrent collaboration:

trellis branch feature/new-parser    # Create + switch
trellis branch                       # List branches
trellis branch -d old-experiment     # Delete

Milestones

Milestones are narrative checkpoints over ranges of ops. Unlike commits, they can be created retroactively and span multiple file changes:

# Create a milestone over the most recent ops
trellis milestone create -m "Implement user authentication"

# Create over a specific range
trellis milestone create -m "Refactor auth" --from <hash> --to <hash>

# List milestones
trellis milestone list

Checkpoints

Checkpoints are auto-generated stability markers. They're created when an op threshold is crossed during trellis watch:

trellis checkpoint list
trellis checkpoint create    # Manual checkpoint

Diff

Trellis supports both file-level and semantic diffs:

# File-level diff between two ops
trellis diff --from <hash> --to <hash>

# Semantic diff (AST-level) between two file versions
trellis sdiff src/old.ts src/new.ts

Semantic diffs produce structured patches: symbolAdd, symbolRemove, symbolModify, symbolRename, importAdd, importRemove.

Merge

Three-way merge with optional semantic conflict resolution:

trellis merge --branch feature/auth
trellis merge --branch feature/auth --dry-run

Issue Tracking

Trellis has first-class issue tracking built into the VCS:

# Create an issue
trellis issue create -t "Add Python parser" -P high \
  --desc "Support Python AST parsing" \
  --ac "test:bun test test/semantic/python"

# Start working (auto-creates branch)
trellis issue start TRL-1

# Check acceptance criteria
trellis issue check TRL-1

# Close when done
trellis issue close TRL-1 --confirm

See the Issue Tracking guide for the full lifecycle.

Core Concepts

The mental model behind Trellis — ops, tiers, the EAV graph, and how everything connects.

Semantic Analysis

AST parsing, semantic diffing, and intelligent merge powered by structural code understanding.