# Getting started

Last updated: 2026-07-21

How to clone Sorrel, run the local VCS demo, and start the Hub stack. Source of
truth for the multi-repo layout is
[github.com/MGRAFF2006/sorrel](https://github.com/MGRAFF2006/sorrel).

## Prerequisites

- **Git** with submodule support
- **Rust** stable 1.85+ with clippy + rustfmt
- **Node.js** 22+ (Hub / hub-web); Node 20+ is enough for protocol/vault/slices
- **Docker** (optional) for `docker compose`

```sh
rustup toolchain install stable --profile minimal -c clippy -c rustfmt
rustup default stable
```

## Clone with submodules

```sh
git clone --recurse-submodules https://github.com/MGRAFF2006/sorrel.git
cd sorrel

# If you already cloned without submodules:
git submodule update --init --recursive
```

## Local VCS happy path (CLI)

```sh
cd sorrel-cli
cargo build
SORREL=target/debug/sorrel

mkdir /tmp/sorrel-demo && cd /tmp/sorrel-demo
$SORREL init
echo hello > a.txt
$SORREL status
$SORREL change create -m "add a.txt"
$SORREL log

$SORREL lane create --name feature
$SORREL lane list
$SORREL lane switch <feature-lane-id>
echo feature > b.txt
$SORREL change create -m "add b"
$SORREL lane switch lane_main
$SORREL merge <feature-lane-id>
```

## Import a Git repository

```sh
cd /path/to/git-checkout
$SORREL git import
# optional: --ref main --limit 20 --json
$SORREL log
$SORREL status
```

One-way only for now (no export / colocated mirror yet).

## Hub API + Hub UI

### Docker Compose (repo root)

```sh
docker compose up --build
```

| Service | URL |
| --- | --- |
| Hub API | http://localhost:3000 |
| Hub UI | http://localhost:5180 |
| Landing (local preview) | http://localhost:4173 |

This landing site’s **production** host is Cloudflare Pages. Compose `web` is
only a local preview.

### Without Docker

```sh
cd sorrel-hub && npm start
cd sorrel-hub-web && npm start
```

## CLI ↔ Hub sync

```sh
$SORREL remote add origin http://127.0.0.1:3000
$SORREL push origin

# fresh directory
$SORREL init
$SORREL remote add origin http://127.0.0.1:3000 --repo-id <repoId>
$SORREL pull origin
```

## Validate

```sh
# Rust modules
cargo test && cargo clippy --all-targets && cargo fmt --all -- --check

# Node modules
npm test
```

## See also

- [STATUS.md](STATUS.md) — working vs missing
- [Roadmap](https://github.com/MGRAFF2006/sorrel/blob/main/ROADMAP.md)
- [Progress](https://github.com/MGRAFF2006/sorrel/blob/main/SORREL_PROGRESS.md)
- [Architecture](https://github.com/MGRAFF2006/sorrel/blob/main/AGENT_NATIVE_VERSION_CONTROL_REPORT.md)