temp for tree extraction
This commit is contained in:
247
README.md
Normal file
247
README.md
Normal file
@ -0,0 +1,247 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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](https://github.com/go-git/go-git) - Git implementation in pure Go
|
||||
- [cobra](https://github.com/spf13/cobra) - CLI framework
|
||||
- [fsnotify](https://github.com/fsnotify/fsnotify) - Filesystem monitoring
|
||||
Reference in New Issue
Block a user