# Benchmarking
> Measure `rift create` performance with `create` and `compare` Cargo benches, sample counts, JSON output schema, and candidate comparison workflow.
- Repository: anomalyco/rift
- GitHub: https://github.com/anomalyco/rift
- Human docs: https://grok-wiki.com/public/docs/anomalyco-rift-ea3fd5dbf662
- Complete Markdown: https://grok-wiki.com/public/docs/anomalyco-rift-ea3fd5dbf662/llms-full.txt
## Source Files
- `README.md`
- `crates/core/benches/create.rs`
- `crates/core/benches/compare.rs`
- `crates/core/benches/AUTORESEARCH.md`
- `crates/core/Cargo.toml`
---
---
title: "Benchmarking"
description: "Measure `rift create` performance with `create` and `compare` Cargo benches, sample counts, JSON output schema, and candidate comparison workflow."
---
The `rift` crate (`crates/core`) ships two standalone Cargo bench binaries—`create` and `compare`—that time the production `Manager::create_with_options` path against a real workspace directory. Both benches use `harness = false`, so they run as ordinary binaries invoked through `cargo bench` rather than through Criterion. The `create` bench records per-sample elapsed milliseconds; `compare` orchestrates that bench across multiple candidate checkouts and ranks results by median time.
## What gets measured
The `create` bench exercises the same code path the CLI uses for workspace creation, with two deliberate isolations from unrelated overhead:
| Phase | Included in timing? | Notes |
| --- | --- | --- |
| `Manager::init` on the workload | No | Runs once before the sample loop |
| `Manager::create_with_options` | Yes | Production copy strategy and registry registration |
| Postcreate hooks | No | `HookMode::Skip` disables `.rift.toml` hook execution |
| `Manager::remove` + `Manager::gc` | No | Runs after each sample to reset state for the next run |
Each timed sample creates a uniquely named child workspace (`benchmark-{pid}-{run_id}-{sample}`), then removes it and runs garbage collection so later samples start from a clean registry state.
The benchmark uses the production filesystem strategy selected at runtime. On macOS that means APFS `clonefile`; on Linux btrfs that means subvolume snapshots; on reflink-capable Linux filesystems that means per-file reflinks. Results are not comparable across platforms.
## Bench targets
Both targets are declared in `crates/core/Cargo.toml`:
```toml
[[bench]]
name = "create"
harness = false
[[bench]]
name = "compare"
harness = false
```
Run them from the repository root or from `crates/core`. `cargo bench` compiles with release optimizations by default.
## `create` benchmark
### Command
```bash
cargo bench --bench create -- /path/to/workspace [--samples N] [--output /path/to/result.json]
```
Directory to initialize and use as the create source. Must exist. The bench canonicalizes this path before timing.
Number of independent create operations to time. Must be greater than zero.
Optional file path. When set, writes a JSON result document after all samples complete.
### Stdout
Each sample prints a tab-separated progress line:
```text
create 1/10 37.842 ms /path/to/.rifts/benchmark-12345-...
```
When `--samples` is greater than 1, a summary line follows:
```text
median 37.800 ms min 37.600 ms max 38.100 ms
```
On failure the bench prints `benchmark failed: {error}` to stderr and exits with code `1`.
### Establish a baseline
Measure multiple independent creations and persist machine-readable output outside the workload directory so result files do not alter future measurements:
```bash
mkdir -p /path/to/results
cargo bench --bench create -- /path/to/linux \
--samples 10 \
--output /path/to/results/baseline.json
```
Use `median_ms` as the primary comparison metric. Keep `samples_ms` to detect noisy runs.
## `create` JSON output schema
When `--output` is set, the bench writes a single JSON object:
Always `"create"`.
Wall-clock milliseconds since Unix epoch at write time.
`std::env::consts::OS` value (for example `"linux"`, `"macos"`).
Canonicalized workload directory path.
Elapsed milliseconds for each sample, in run order.
Median of `samples_ms`. For even sample counts, the average of the two middle values.
Minimum value in `samples_ms`.
Maximum value in `samples_ms`.
Always `true` when the bench exits successfully. The `compare` bench rejects candidates where this is `false`.
```json
{
"benchmark": "create",
"timestamp_ms": 1718640000123,
"platform": "macos",
"source": "/path/to/linux",
"samples_ms": [37.8, 38.1, 37.6, 37.9, 38.0],
"median_ms": 37.8,
"min_ms": 37.6,
"max_ms": 38.1,
"cleanup_passed": true
}
```
## `compare` benchmark
The `compare` bench runs each candidate's `create` bench against the same workload, collects per-candidate JSON results, and writes a ranked summary.
### Command
```bash
cargo bench --bench compare -- /path/to/workload \
--candidate /path/to/rift \
[--candidate /path/to/rift-other] \
--output /path/to/results \
[--samples N]
```
Workload directory passed through to every candidate's `create` bench. Canonicalized before execution.
Repeatable. Each path must be a Cargo workspace root containing `Cargo.toml` and the `create` bench target. At least one candidate is required.
Output directory. Created if missing, then canonicalized. Receives per-candidate JSON files and `summary.json`.
Sample count forwarded to each candidate's `create` bench.
### How candidates are invoked
For each `--candidate` path, `compare` runs:
```bash
cargo bench --locked --bench create -- --samples --output