How it Works

Everything you need to know to work with Catena.

What is Catena?

Catena is a patch-based version control system. Every change is a Patch — an atomic package of file operations. Patches are chained together in a linear sequence.

Patches, not Commits
Every change is a self-contained, reviewable package

│

Trunk, not Branches
One single truth, no diverging histories

Overlap Detection
Conflicts are detected immediately, not at integration time

↕

Online-first
The server is the source of truth, sync is trivial

💬

Inline Comments
Comment directly on code lines in a patch

Core Concepts

Patches

A patch is a collection of file operations:

+ Insert ~ Modify - Delete > Rename

Every patch has an author, description, timestamp, and a Maturity level.

Trunk

The trunk is the current, correct state of the project. No main branch, no develop. Just the trunk. When a patch is accepted, the trunk grows — patch by patch, linearly.

Maturity — The Lifecycle of a Patch

DraftLocal

→

DraftSynced

→

DraftShared

→

Proposed

→

Accepted

DraftLocal Created locally, not yet synced

DraftSynced Saved on server, only visible to you

DraftShared Shared with team, others can build dependencies on it

Proposed Submitted for review — candidate for the trunk

Accepted Merged into trunk — now part of the truth

Withdraw: A proposed patch can be pulled back to DraftSynced with catena withdraw to continue working on it.

Overlaps (Conflicts)

When two proposed patches modify the same file, Catena detects it immediately:

Payment Retry

overlap

Email Notifications

● Auto-Apply — Different files, no problem

● Deduplicated — Same change, merged automatically

● Conflict — Same file, different change → must be resolved

Overlaps are highlighted in red on the Timeline and in the Patches view.

Dependencies

Patches can depend on each other. A patch can only be accepted once all its dependencies are accepted.

Frontend Types

API Auth Refactor

Payment Retry

Email Notify

Trunk (accepted)

Accept order: Payment + Email → API Auth → Frontend Types

Sync

Your Workspace

💻

sync up ↑

↓ sync down

Server (Trunk)

☁️

$ catena sync down # Server → Local (Pull)

$ catena sync up -m "My fix" # Local → Server (Push)

$ catena sync down --patch abc123 # Trunk + test a patch

Safety: catena sync without down asks for confirmation if you have local changes. With explicit catena sync down it doesn't ask — you know what you're doing.

Roles

Developer Create patches, propose, withdraw, view status

Maintainer + Accept patches, create releases

Admin + Manage users, assign roles

Getting Started

Start the server

$ dotnet run --project src/Catena.Server

Admin API Key: xxxxxxxx

On first run an admin key is displayed. Save it!

Create a project

$ catena init --new "My Project" --api-key <KEY>

Workspace initialized in .catena/

Make changes & check status

$ echo "Hello" > hello.txt

$ catena status

+ hello.txt

1 added, 0 modified, 0 deleted

Push changes

$ catena sync up -m "Add hello"

Synced up: patch abc123 created (1 ops)

Propose & Accept

$ catena propose

Patch abc123 proposed.

$ catena accept abc123

Patch abc123 accepted. Trunk updated.

Workflows

Daily Workflow

catena sync downPull trunk state

↓

Edit files

↓

catena statusWhat changed?

↓

catena sync up -m "..."Push changes

↓

catena proposeSubmit for review

↓

Team comments inline

↓

catena accept <id>Maintainer accepts

Resolving Conflicts

# Alice and Bob modify the same file

OVERLAP detected: Payment Retry × Email Notifications

# Bob withdraws, Alice gets accepted

$ catena withdraw <bob-id>

$ catena accept <alice-id>

# Bob syncs, adjusts, re-proposes

$ catena sync down

$ catena sync up -m "Email v2"

$ catena propose

Building on a Patch

# Pull Alice's patch as your base

$ catena sync down --patch <alice-id>

# Work on top, push with dependency

$ catena sync up -m "Auth service"

$ catena draft --depends-on <alice-id>

$ catena propose

# Accept enforces order: Alice → Bob

Hotfix on Release + Trunk

$ catena release v1.0.0

# Hotfix targeting both

$ catena sync up -m "Hotfix login"

$ catena draft --target trunk --target v1.0.0

# After accept: patch applied to trunk + release

CLI Reference

catena initCreate or connect a workspace

catena statusShow local changes

catena sync upPush changes to server

catena sync downPull trunk state

catena proposeSubmit patch for review

catena accept <id>Accept patch into trunk

catena withdraw <id>Pull back a proposed patch

catena logShow patch history

catena diff <id>Show patch details

catena release <v>Create release snapshot

catena draftSet dependencies / targets

Web UI

Available at /app after login.

■

Dashboard

Overview: stats, activity feed, overlap count

▶

Patches

Master-detail with diff, inline comments, overlaps

⋮

Timeline

Patch chain graph with dependencies and overlaps

☰

Files

Trunk file tree with code viewer

●

Releases

Frozen snapshots with version tags

⚙

Settings

Team, roles, API keys, webhooks

The UI updates live — when someone creates or accepts a patch via CLI or API, you see it instantly in the browser.

Design Decisions

Trunk, not Branches

Catena has one trunk — the single source of truth. Parallel work happens through proposed patches: they live side by side, not in separate histories. Overlap detection shows immediately when two patches collide.

Online-first

The server is the source of truth. Sync is trivial, overlaps are instantly visible, comments are native. You can still work offline: catena draft creates local drafts.

Linear History

Every patch is atomic — either fully in trunk or not at all. The history is a chain, not a graph. This makes it easier to understand and debug.