Login
Cambria: a SQLite-backed version control system in Go
Login

Cambria is a standalone version control system inspired by Fossil SCM. A repository is a single SQLite database file (*.db) containing versioned content, history, branches/tags, and working-directory state.

The implementation uses Go, with SQLite provided by github.com/mattn/go-sqlite3 (CGo).

Cambria is based on ideas, design, and implementation from Fossil and SQLite, created by D. Richard Hipp.

Design

Design and implementation notes:

Current Features

Local Version Control

Cambria supports full local (single-machine) workflows:

Network and Distributed Version Control

Cambria has a fully-featured network stack for distributed workflows:

REST API

The cambria serve command also exposes a versioned REST API for automation and integration:

See doc_cambria/SYNC_IMPLEMENTATION_SUMMARY.md for details on the network stack and how to add new endpoints.

Web UI and Todo App (In Progress)

Cambria is being developed as a web application platform with server-side rendering:

A small todo-list MVP demonstrates the collection-style app model:

The web UI will continue to evolve into a full application platform inspired by PocketBase, with features like user-defined data collections, real-time updates, and "docs as code" content management. See CAMBRIA_APP_TODO_PLAN.md and CAMBRIA_UI_PLAN.md for the roadmap.

HTTP Server and Sync Protocol

Cambria includes an HTTP server with authentication and a sync protocol:

Planned Features

Development is ongoing. The following major features are planned for future releases:

  1. Additional REST Endpoints:
    • GET /api/v1/status - Working directory status
    • GET /api/v1/artifact/{uuid} - Individual artifact retrieval for web UIs
    • Branch, tag, timeline, and user management endpoints
  2. Web UI Expansion (currently in progress):
    • Timeline view for version history
    • User authentication and session management for browser-based workflows
    • Data collections API for user-defined schemas
    • Real-time updates via Server-Sent Events (SSE)
    • Markdown editor integration
  3. Configuration: Support for repository-specific settings in a .cambria/config file.
  4. Ignore Patterns: A .cambriaignore file for excluding files from version control.

... For implementation details:

Getting Started

Prerequisites

Build from Source

  1. Clone the repository:

   mkdir cambria
   cd cambria
   fossil clone https://<username>:<password>@ipsaw.com/cambria cambria.fossil
   fossil open cambria.fossil

  1. Build the cambria binary:

   go build -o cambria ./cmd/cambria

You can now move the cambria executable to a directory in your $PATH.

Quick Start Workflow

  1. Initialize a new repository:

   cambria init my-project.db

  1. Create a working directory and open the repository:

   mkdir my-project-work
   cd my-project-work
   cambria open ../my-project.db

This creates a _cambria file that links this directory to the repository database.

  1. Add files and make your first commit:

   echo "Hello, Cambria!" > README.md
   cambria add README.md
   cambria commit -m "Initial commit"

  1. Check the status:

   cambria status

  1. Create a branch and switch to it:

   cambria branch feature/new-idea
   cambria checkout feature/new-idea

  1. Make changes and merge them back:

```sh echo "A new feature." > feature.txt cambria add feature.txt cambria commit -m "Implement amazing new feature"

cambria checkout main cambria merge feature/new-idea cambria commit -m "Merge new feature" ```

Project Structure Overview

cambria/
├── cmd/cambria/    # CLI application source
├── pkg/
│   ├── artifact/   # Manifest parsing and generation
│   ├── auth/       # Authentication and authorization (Argon2id, permissions)
│   ├── hash/       # Content hashing (SHA-256)
│   ├── httpapi/    # HTTP server, middleware, and REST handlers
│   ├── store/      # SQLite data access layer
│   ├── sync/       # Sync protocol (client, server, exchange logic)
│   └── vcs/        # High-level version control operations
├── internal/       # Internal helper packages
├── doc_cambria/    # Detailed implementation documentation
└── go.mod          # Go module definition

For implementation details:

Building and Testing

go build ./...
go test ./...
go test -race ./...
go test -cover ./...
go fmt ./...

Coverage notes (from go test -cover ./...):

External Dependencies

Cambria keeps external dependencies minimal and prefers well-maintained, MIT licensed libraries when the standard library is insufficient. Notable dependencies include:

Copyright (c) 2026 Nicholas Hildebrant. All rights reserved.