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

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

License

[License information to be added]

Acknowledgments

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