cambria

Cambria - Version Control System in Go
Login

Cambria is a version control system implemented in Go that aims to achieve feature parity with Fossil SCM's core version control and data model capabilities.

Project Status: Phase 2 Complete ✓

The project has completed foundational infrastructure (Phase 0), core version control operations (Phase 1), working directory state tracking (Phase 1.5), and command-line interface (Phase 2). The VCS is now functional and ready for advanced features.

Current Phase Summary

✅ Phase 0 (Foundation) - Complete

✅ Phase 1 (Version Control Operations) - Complete

✅ Phase 1.5 (VFILE Working Directory Tracking) - Complete

✅ Phase 2 (CLI & User Interface) - Complete

🔄 Phase 3 (Advanced Features) - Next

See AGENTS.md for detailed implementation status.

What's Been Accomplished

Phase 0: Foundation ✅

Phase 1: Version Control Operations ✅

Phase 1.5: VFILE Working Directory Tracking ✅

Documentation: See doc_cambria/CAMBRIA_VFILE_IMPL.md for detailed implementation documentation.

Phase 2: CLI & User Interface ✅

Documentation: See doc_cambria/CAMBRIA_CLI_PLAN.md for detailed CLI specifications.

Project Structure

cambria/
├── go.mod                      # Go module definition
├── go.sum                      # Dependency checksums
├── README.md                   # Project documentation (this file)
├── AGENTS.md                   # Implementation guide for AI agents
│
├── pkg/
│   ├── hash/                   # Content hashing utilities (SHA-256)
│   │   ├── hash.go             # Hash computation and verification
│   │   └── hash_test.go        # 91.7% coverage
│   │
│   ├── store/                  # SQLite data access layer
│   │   ├── db.go               # Database connection management
│   │   ├── dbtx.go             # Transactional interface
│   │   ├── schema.go           # Schema creation (includes vfile/vmerge)
│   │   ├── blob.go             # Blob storage operations
│   │   ├── manifest.go         # Manifest storage operations
│   │   ├── mlink.go            # Manifest-file linkage
│   │   ├── plink.go            # Parent-child linkage
│   │   ├── label.go            # Tag/branch labels
│   │   └── *_test.go           # 80.7% coverage total
│   │
│   ├── artifact/               # Artifact parsing and generation
│   │   ├── manifest.go         # Manifest format parsing/serialization
│   │   └── manifest_test.go    # 93.3% coverage
│   │
│   └── vcs/                    # High-level version control operations
│       ├── repo.go             # Repository initialization and management
│       ├── checkin.go          # Commit/checkin operations (uses vfile)
│       ├── checkout.go         # Checkout operations (populates vfile)
│       ├── add.go              # File addition (updates vfile)
│       ├── diff.go             # Diff computation
│       ├── workdir.go          # Working directory state (uses vfile)
│       ├── vfile.go            # VFILE system implementation
│       ├── vfile_test.go       # VFILE unit tests (8 tests)
│       ├── vfile_integration_test.go  # VFILE integration tests (3 tests)
│       ├── checkout_test.go    # Checkout tests
│       └── main_test.go        # VCS integration tests
│
├── internal/                   # Private packages
│   └── testutil/               # Test utilities and helpers
│       └── testutil.go
│
├── cmd/                        # Command-line application
│   └── cambria/                # CLI (Phase 2 complete)
│       ├── main.go             # CLI entry point
│       ├── common.go           # Shared utilities (repo discovery, version resolution)
│       ├── init.go             # init command
│       ├── add.go              # add command
│       ├── commit.go           # commit/ci command
│       ├── checkout.go         # checkout/co command
│       ├── status.go           # status command
│       ├── diff.go             # diff command
│       ├── open.go             # open command
│       └── close.go            # close command
│
├── testdata/                   # Test fixtures and golden files
│   ├── manifests/
│   └── repos/
│
└── doc_cambria/                # Design documentation
    ├── CAMBRIA_PHASE_0.md      # Phase 0 specification
    ├── CAMBRIA_PHASE_1.md      # Phase 1 specification
    ├── CAMBRIA_VFILE_IMPL.md   # Phase 1.5 implementation (VFILE system)
    ├── CAMBRIA_CLI_PLAN.md     # Phase 2 specification (next)
    ├── CAMBRIA_DATA_MODEL_DESIGN.md
    ├── FOSSIL_VERSION_CONTROL.md
    └── FOSSIL_VERSION_CONTROL_TEST.md

Module Information

Building and Testing

Prerequisites

Environment Setup

# Ensure CGo is enabled
export CGO_ENABLED=1

# Verify Go installation
go version  # Should show: go version go1.25.5 linux/amd64

Build

# Build all packages
go build ./...

# Build CLI
go build -o cambria ./cmd/cambria

# Install to $GOPATH/bin
go install ./cmd/cambria

Static Build (musl)

You can produce a fully static cambria binary using musl and cgo (required for github.com/mattn/go-sqlite3). Ensure musl-tools is installed.

Quick commands:

export CGO_ENABLED=1
export CC=musl-gcc
go build -v -tags 'sqlite_omit_load_extension' -ldflags '-linkmode external -extldflags "-static"' ./cmd/cambria

# Verify static linking
file ./cambria
ldd ./cambria || true

Makefile targets:

make static   # builds ./cambria as a static binary
make verify   # prints file type and ldd output
make clean    # removes ./cambria

VS Code tasks:

Tasks are defined in .vscode/tasks.json.

Test

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with race detector (CRITICAL before committing)
go test -race ./...

# Run specific package tests
go test ./pkg/vcs
go test ./pkg/vcs -v  # Verbose output

Code Quality

# Format code
go fmt ./...

# Static analysis
go vet ./...

# View test coverage
go test -cover ./...

Package Overview

pkg/hash

Content-addressable hashing utilities using SHA-256.

Key Functions:

pkg/store

SQLite data access layer for all repository data.

Key Operations:

Database Schema:

pkg/artifact

Parse and generate manifest artifacts in canonical text format.

Key Functions:

Manifest Format:

F <path> <file-uuid>          # File entry
P <parent-uuid> [<parent2>]   # Parent manifest(s)
C <comment>                   # Commit message
T <label>                     # Tag/branch label

pkg/vcs

High-level version control operations and repository management.

Key Operations:

VFILE System (Phase 1.5):

Security Features:

internal/testutil

Test utilities and helpers for writing tests.

Key Functions:

Test Coverage Summary

Package Coverage Tests Notes
pkg/hash 91.7% 8 tests SHA-256 hashing
pkg/store 80.7% 68 tests SQLite operations
pkg/artifact 93.3% 13 tests Manifest parsing
pkg/vcs ~80% 31 tests VCS operations + VFILE
Total 80%+ 120+ tests All passing ✅

VFILE Tests (Phase 1.5):

Design Philosophy

Usage

Quick Start

# Build the CLI
go build -o cambria ./cmd/cambria

# Initialize a new repository
cambria init myproject.db

# Create a working directory and make initial commit
mkdir work && cd work
echo "Hello World" > test.txt
cambria -R ../myproject.db commit -m "Initial commit"

# Add and commit more files
echo "New content" > newfile.txt
cambria add newfile.txt
cambria commit -m "Add newfile"

# Check status
cambria status

# View differences (Note: diff for working directory has known issue)
# cambria diff --from <uuid> --to <uuid>

# Checkout different versions
cambria checkout --force <uuid-prefix>

Workflow

  1. Initialize: cambria init repo.db creates a new repository
  2. First Commit: cambria -R repo.db commit -m "Initial" creates initial commit and sets up working directory with _cambria metadata file
  3. Subsequent Operations: Commands automatically find repository via _cambria file
  4. Add Files: cambria add <files> stages files for commit
  5. Commit: cambria commit -m "message" creates new manifest
  6. Status: cambria status shows working directory state
  7. Checkout: cambria checkout <version> switches to different version

Known Issues

Next Steps: Phase 3 (Advanced Features)

Phase 3 will implement advanced version control features:

Planned Features

  1. Timeline/Log - Show commit history with cambria timeline or cambria log
  2. Branch Management - Create and switch branches with cambria branch
  3. Tag Management - Advanced tagging beyond commit-time labels
  4. Merge Operations - Merge branches with conflict resolution
  5. File Operations - rm, mv commands for tracked files
  6. Network Operations - clone, push, pull, sync for remote repositories
  7. Configuration - Support for .cambria/config files
  8. Ignore Patterns - Enhanced .cambriaignore support
  9. Web UI - Optional web interface like Fossil's ui command

Documentation

Project Documentation

Phase Documentation

Design Documentation

Reference

Future Reference

License

[To be determined]

Contributing

Phases 0, 1, 1.5, and 2 are complete. The VCS is now functional with a working CLI. Work on Phase 3 (Advanced Features) can now begin.

See AGENTS.md for detailed implementation guidance and current project status.

Current Status: ✅ Phase 2 Complete - Command-Line Interface Next Milestone: 🔄 Phase 3 - Advanced Features (branches, merge, timeline, network) All Tests: ✅ 120+ tests passing, no race conditions Test Coverage: ✅ 80%+ across all packages CLI Status: ✅ Functional with core commands (init, add, commit, checkout, status, diff)