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:

```bash
# 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:

```bash
# 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:

```bash
# 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
```bash
# Save changes (like git add + git commit)
onx save -m "Add new feature"
```

### Push to Remote
```bash
# Push your work (default: single branch mode)
onx push

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

### Create a New Workstream
```bash
# 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
```bash
# 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
```bash
# See all your workstreams (like git branch)
onx list
```

### Sync with Remote
```bash
# Update from remote (like git pull --rebase)
onx sync
```

### Undo Operations
```bash
# 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)
```bash
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)
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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.**