Add migration guidance for removed --reference option

src/cli.rs

@@ -50,6 +50,19 @@ fn build_command() -> Command {
                 .value_hint(ValueHint::CommandString)
                 .value_parser(NonEmptyStringValueParser::new()),
         )
+        // Retain the removed option to provide migration guidance for old invocations.
+        .arg(
+            Arg::new("reference")
+                .long("reference")
+                .hide(true)
+                .value_name("CMD")
+                .num_args(0..=1)
+                .default_missing_value("")
+                .value_parser(|_: &str| -> Result<String, String> {
+                    Err("The --reference option has been removed. Put your reference command first instead.".into())
+                })
+                .help("Removed: put your reference command first instead."),
+        )
         .arg(
             Arg::new("metrics")
                 .long("metrics")

tests/integration_tests.rs

@@ -44,6 +44,25 @@ fn runs_successfully() {
         .success();
 }
 
+#[test]
+fn rejects_removed_reference_option_with_migration_guidance() {
+    for args in [
+        vec!["--reference", "echo reference", "echo comparison"],
+        vec!["echo comparison", "--reference=echo reference"],
+        vec!["--reference", "echo reference"],
+        vec!["--reference"],
+    ] {
+        hyperfine()
+            .args(args)
+            .assert()
+            .code(2)
+            .stdout("")
+            .stderr(predicate::str::contains(
+            "The --reference option has been removed. Put your reference command first instead.",
+        ));
+    }
+}
+
 #[test]
 fn one_run_is_supported() {
     hyperfine()