Onyx

A next-generation version control system designed as a superior user experience layer on top of Git.

Overview

Onyx provides transparent versioning, workstreams for stacked-diff management, and an action log for universal undo functionality. The project is written in Go and uses the go-git library for Git interaction.

Features

• 100% Git Data Model Compatibility: Uses standard .git directory for shared truth
• Transparent Versioning: Background daemon creates continuous snapshots
• Workstreams: Stacked-diff workflow management
• Action Log: Transactional undo/redo capability
• Hybrid Storage: .git for Git objects, .onx for Onyx-specific metadata

Quick Start

Prerequisites

• Go 1.24.2 or later
• Git 2.30.0 or later

Installation

# Clone the repository
git clone https://git.dws.rip/DWS/onyx.git
cd onyx

# Install dependencies
go mod tidy

# Build the CLI and daemon
make build

# Install to PATH
make install

Usage

# Initialize repository
onx init

# Create workstream
onx new feature-branch

# Save work
onx save -m "Add new feature"

# List workstreams
onx list

# Switch workstreams
onx switch main

# Sync with remote
onx sync

# Push workstream
onx push

# Undo last operation
onx undo

Development

Building

# Build the CLI and daemon
go build -o bin/onx ./cmd/onx
go build -o bin/onxd ./cmd/onxd

# Install to PATH
go install ./cmd/onx
go install ./cmd/onxd

Testing

# Run all tests
go test -v ./...

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

# Run specific test package
go test -v ./internal/core

Linting and Code Quality

The project uses several tools to maintain code quality:

# Run linter
golangci-lint run

# Run security scanner
gosec ./...

# Run tests with race detection
go test -race ./...

CI/CD

This project uses Gitea Actions for continuous integration and deployment. The workflow includes:

CI Pipeline

• Test: Runs unit tests with race detection and coverage reporting
• Build: Cross-compiles binaries for multiple platforms (Linux, Windows, macOS)
• Security: Runs security scans using Gosec
• Lint: Performs comprehensive code linting with golangci-lint
• Release: Creates releases and uploads artifacts for main branch builds

Supported Platforms

• Linux (amd64, arm64)
• Windows (amd64)
• macOS (amd64, arm64)

Workflow Triggers

• Push to main or develop branches
• Pull requests to main branch

Architecture

Project Structure

onyx/
├── cmd/
│   ├── onx/           # CLI entry point
│   └── onxd/          # Daemon entry point
├── internal/
│   ├── core/          # Core abstractions
│   ├── git/           # Git interaction layer
│   ├── models/        # Data models
│   ├── storage/       # .onx directory management
│   ├── commands/      # CLI command implementations
│   ├── daemon/        # Daemon implementation
│   └── utils/         # Utilities
├── pkg/               # Public APIs
├── test/              # Integration tests
└── docs/              # Documentation

Core Components

• Repository: Central object encapsulating access to both Git repository and Onyx metadata
• Action Log: Append-only binary log storing state before/after each operation
• Workstreams: Manages stacked-diff workflows through .onx/workstreams.json
• Daemon: Background process for continuous snapshot creation

Contributing

1. Fork the repository
2. Create a feature branch (onx new feature-name)
3. Make your changes
4. Run tests and linting (make test lint)
5. Commit your changes (onx save -m "Add feature")
6. Push to your fork (onx push)
7. Create a pull request

License

[License information to be added]

Acknowledgments

• go-git - Git implementation in pure Go
• cobra - CLI framework
• fsnotify - Filesystem monitoring