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

Push Workflows: Single-Branch vs Stacked Diffs

Onyx supports two push workflows to match your team's needs:

Single-Branch Mode (Default) - Recommended

Perfect for: Traditional teams, simple features, clean remote UI

onx new add-login --base main
onx save -m "Add login form"
onx save -m "Add validation"
onx save -m "Add tests"

# Push creates ONE branch with all commits
onx push

# Result on remote:
# - Branch: add-login (contains all 3 commits)
# - Clean UI, easy PR workflow

What you get:

• ✅ One clean branch per workstream
• ✅ Perfect for traditional PR workflows
• ✅ All commits preserved locally for undo
• ✅ Clean remote repository UI

Stacked Diffs Mode - Advanced

Perfect for: Complex features, incremental review, Meta/Google-style workflows

onx new big-refactor --base main
onx save -m "Step 1: Database schema"
onx save -m "Step 2: API endpoints"
onx save -m "Step 3: Frontend UI"

# Push creates MULTIPLE branches (one per commit)
onx push --stacked

# Result on remote:
# - Branch: onyx/workstreams/big-refactor/commit-1
# - Branch: onyx/workstreams/big-refactor/commit-2
# - Branch: onyx/workstreams/big-refactor/commit-3
# - Each can have its own PR for focused review

What you get:

• ✅ One branch per commit for incremental review
• ✅ PRs can be merged independently
• ✅ Better for large, complex changes
• ⚠️ More branches in remote UI

Choosing Your Workflow

Criterion	Single-Branch (onx push)	Stacked Diffs (onx push --stacked)
Team Style	Traditional Git workflow	Meta/Google stacked review
Feature Size	Any size	Large, complex features
Review Style	One big PR	Multiple small PRs
Remote UI	Clean (1 branch)	More branches (N commits)
PR Creation	gh pr create --head feature	Multiple PRs, stacked dependencies

Recommendation: Start with default onx push (single-branch). Use --stacked only when you need incremental review of complex changes.

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