Doctor and benchmarking

Project diagnosis

Run:

cargo warm doctor

With one checkout, the doctor runs in project-only mode. It reports:

• the active cargo-warm profile and config;
• selected Cargo packages and manifests;
• Rust toolchain/channel support;
• local Rust source size;
• direct and path-dependency build scripts;
• current Cargo cache shape;
• clone pressure, seedable cache-root count, and effective clone workers;
• whether Cargo has a separate intermediate build-dir or still mixes build cache and final target artifacts;
• a recommended profile and alternatives worth testing.

The recommendation is deliberately a starting point, not an oracle. Static analysis cannot know whether your build.rs takes 20ms or two minutes, nor what kind of edit dominates your real workflow.

Compare two worktrees

If a warm checkout and a new worktree both exist, cargo-warm automatically selects a compatible warm peer. You can also be explicit:

cargo warm doctor \
  --from /repo/main \
  --to /repo/worktrees/feature

The comparison adds:

• Git revision/cleanliness checks;
• tracked-file mtime skew;
• safe freshness candidates;
• checkout-local build-script paths;
• ignored native outputs cargo-warm can materialize automatically;
• source/destination cache presence.

Use JSON when another tool or agent should consume the report:

cargo warm doctor --json

Ask Cargo why it rebuilds

Static diagnosis does not compile. When you need the actual dirty reasons, add --probe:

cargo warm doctor --probe

Probe mode runs cargo check with Cargo fingerprint logging enabled and groups common causes such as:

• changed files;
• build-script watched-path changes;
• dependency fingerprint changes;
• environment/config changes;
• compiler changes;
• filesystem freshness misses.

Because it can compile code, use --probe after the cheap diagnosis points you at a real question.

Tune worktree clone time separately

Compiler profiles and clone pressure answer different questions. Keep the compiler profile fixed while measuring clone settings:

cargo warm seed --profile quick --clone-pressure gentle --timings
cargo warm seed --profile quick --clone-pressure auto --timings
cargo warm seed --profile quick --clone-pressure fast --timings

--timings prints the source/manifest preflight, cache clone + freshness planning, native-state handling, freshness synchronization, optional prime, and total seed time.

Always use a fresh destination worktree for each sample. Clone-on-write filesystem caches are noisy, so compare several samples or medians rather than one run.

If the doctor reports only one seedable cache root, clone pressure cannot create root-level parallelism. If it reports several, auto is the starting point; an explicit clone-workers = N is useful when you have measured a stable project/machine-specific sweet spot.

Benchmark profiles correctly

Use a fresh worktree for each sample. Reusing one destination lets the first run warm the second and makes the comparison meaningless.

A good loop is:

1. Keep one source checkout warm and quiescent.
2. Keep source commit/toolchain/config identical across samples.
3. Create a new worktree at that revision.
4. Time cargo warm seed --profile <profile>.
5. Make one representative Rust edit in the package you care about.
6. Time the same compiler command your developers/agents normally use.
7. Repeat a few times and compare medians.

Measure at least two numbers:

provisioning latency
first representative edit latency

A third useful number is a second edit in the same worktree, which tells you whether a slow first edit is a one-time relocation cost or the project’s normal incremental cost.

What to compare

Typical choices:

• quick vs balanced when the project is medium/large but has no important direct build script.
• balanced vs deep when a very large direct package has a build script and the first edit remains slower than the warm source checkout.
• cache cleanup vs no cleanup when the doctor reports an unusually large stale deps/ population.
• auto vs fast clone pressure when several independent Cargo cache roots exist and worktree creation latency is important.

deep deliberately makes the selected package’s own build script stale during provisioning. If that build script drives an expensive native toolchain, include that cost in the benchmark instead of hiding it.

Interpreting results

Prefer the cheapest profile that gets the agent-visible first-edit latency close to the normal warm-source range.

If none of the profiles do:

1. run doctor --probe;
2. inspect build-script path blockers;
3. verify the source checkout was warmed with the same cargo warm check artifact family used by the destination;
4. check whether stale cache volume itself is hurting Cargo;
5. only then add explicit seed-paths or project-specific build controls.