From 4e081f57d87c92981d196cfd31897b0d7af0e6a5 Mon Sep 17 00:00:00 2001
From: Solaris-star <820622658@qq.com>
Date: Mon, 20 Jul 2026 03:20:11 +0800
Subject: [PATCH] docs: explain --reference with --prepare and parameters

Document that --reference is a separate baseline command (not a
parameter selector) and show how multi --prepare interacts with a
reference plus parameterized benchmarks.

Signed-off-by: Solaris-star <820622658@qq.com>
---
 README.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/README.md b/README.md
index ff6020064..41a43384a 100644
--- a/README.md
+++ b/README.md
@@ -87,6 +87,44 @@ option:
 hyperfine -L compiler gcc,clang '{compiler} -O2 main.cpp'
 ```
 
+### Relative comparisons with a fixed reference
+
+By default, hyperfine compares every benchmark against the **fastest** command.
+Use `--reference <cmd>` when you want a fixed baseline instead (for example, a
+known-good binary or a specific configuration). Optionally name it with
+`--reference-name`.
+
+```sh
+hyperfine --reference 'python3 old_script.py' 'python3 new_script.py'
+```
+
+#### Combining `--reference` with `--prepare` and parameters
+
+`--reference` is a **separate** command string. It is **not** a selector for one
+of the parameterized benchmark variants produced by `--parameter-list` /
+`--parameter-scan`.
+
+Preparation commands substitute parameters from the command they prepare:
+
+- With a single `--prepare '… {param} …'`, parameter substitution works for the
+  parameterized benchmarks, but the reference command has **no** parameters, so
+  placeholders like `{delay}` stay literal and typically fail.
+- To give the reference its own preparation (and keep parameterized prepares for
+  the other commands), pass one `--prepare` per command **including** the
+  reference. The reference is always the first command in that sequence:
+
+```sh
+# reference prepare first, then one prepare template for each parameterized run
+hyperfine -L delay 0.2,0.4,0.6 \
+  --prepare 'sleep 0.4' \
+  --prepare 'sleep {delay}' \
+  --reference 'echo baseline' \
+  'echo a'
+```
+
+If you only need relative speeds among the parameterized commands, omit
+`--reference` and let hyperfine use the fastest run as the baseline.
+
 ### Intermediate shell
 
 By default, commands are executed using a predefined shell (`/bin/sh` on Unix, `cmd.exe` on Windows).