onyx/BOOTSTRAP.md

Getting Started with Onyx

Onyx is a next-generation version control system built on top of Git. These instructions will help you set up your repository using only Onyx commands - no Git knowledge required.

Create a New Repository

Start a brand new project with Onyx:

# Navigate to your project directory
cd /path/to/your/project

# Initialize Onyx with a remote repository
onx init --remote https://git.example.com/username/repo.git

# Save your initial work
onx save -m "Initial commit"

# Push to the remote
onx push

That's it! Your repository is now live.

---

Push an Existing Repository

Already have a project with files? Convert it to Onyx:

# Navigate to your existing project
cd /path/to/existing/project

# Initialize Onyx with your remote
onx init --remote https://git.example.com/username/repo.git

# Save all your existing work
onx save -m "Initial commit - existing project"

# Push everything to the remote
onx push

---

Convert a Git Repository to Onyx

Already using Git? Add Onyx on top:

# Navigate to your Git repository
cd /path/to/git/repo

# Initialize Onyx (remote already configured via Git)
onx init

# You're ready to use Onyx commands!
onx save -m "Convert to Onyx"
onx push

---

Common Next Steps

After bootstrapping, here are the most common workflows:

Save Your Work

# Save changes (like git add + git commit)
onx save -m "Add new feature"

Push to Remote

# Push your work (default: single branch mode)
onx push

# Push as stacked diffs (advanced)
onx push --stacked

Create a New Workstream

# Create a new workstream for a feature (like git checkout -b)
onx new feature-name

# Or specify a base branch
onx new feature-name --base main

Switch Workstreams

# Switch to a different workstream (like git checkout)
onx switch other-feature

# Force switch even with uncommitted changes
onx switch other-feature --force

List Workstreams

# See all your workstreams (like git branch)
onx list

Sync with Remote

# Update from remote (like git pull --rebase)
onx sync

Undo Operations

# Undo your last operation
onx undo

---

Understanding Workstreams

Onyx uses workstreams instead of branches:

• Workstream = A logical stream of work (like a feature branch)
• Automatic creation = When you onx init, Onyx creates a workstream matching your current Git branch
• Clean workflow = Each workstream manages a stack of commits

Push Modes

Onyx supports two push workflows:

Single-Branch Mode (Default - Recommended)

onx push

• Pushes workstream as one branch with all commits
• Clean remote UI (one branch per workstream)
• Perfect for traditional pull requests
• Best for most workflows

Stacked Diffs Mode (Advanced)

onx push --stacked

• Pushes each commit as a separate branch
• Enables incremental review (Meta/Google style)
• Each commit can have its own PR
• More complex remote UI

Pro tip: Stick with default onx push unless you need incremental review.

---

Troubleshooting

"Not an Onyx repository"

You need to run onx init first.

"No changes to commit"

Your working directory is clean. Make some changes first.

"Workstream already exists"

The workstream name is taken. Choose a different name or switch to the existing one.

"Non-fast-forward update"

The remote has changes you don't have locally. Options:

• Run onx sync to update first
• Use onx push --force if you're sure (⚠️ use with caution)

"Remote validation failed"

The remote doesn't exist or isn't configured. Check:

• Is the remote URL correct?
• Does the remote repository exist?
• Do you have access permissions?

---

Philosophy: No Git Required

Onyx is designed to be 100% self-sufficient. You never need to use Git commands:

What You Want	Git Command	Onyx Command
Save work	git add . && git commit	onx save -m "msg"
Push	git push	onx push
New branch	git checkout -b	onx new
Switch branch	git checkout	onx switch
List branches	git branch	onx list
Update	git pull --rebase	onx sync
Undo	git reset/git reflog	onx undo
Clone	git clone	onx clone

Note: Git commands still work if you need them, but Onyx provides a better experience.

---

Examples

Example 1: New Feature

# Start a new feature
onx new user-authentication

# Make changes to your code
# ...

# Save your work
onx save -m "Add login form"

# Make more changes
# ...

# Save again
onx save -m "Add password validation"

# Push to create a PR
onx push

Example 2: Quick Fix

# Create a hotfix workstream
onx new hotfix-login-bug --base main

# Fix the bug
# ...

# Save and push
onx save -m "Fix login redirect bug"
onx push

Example 3: Complex Feature with Review

# Create feature workstream
onx new complex-feature

# Implement step 1
onx save -m "Step 1: Database schema"

# Implement step 2
onx save -m "Step 2: API endpoints"

# Implement step 3
onx save -m "Step 3: Frontend UI"

# Push as stacked diffs for incremental review
onx push --stacked

# Each commit gets its own branch for separate PRs

---

Need Help?

• Read the full documentation: README.md and CLAUDE.md
• Check the integration guide: INTEGRATION.md
• Report issues: https://github.com/anthropics/claude-code/issues

---

Welcome to Onyx - Version control that makes sense.