From 26760e8365f5a7122fa9533d5120d8953dd68c1b Mon Sep 17 00:00:00 2001
From: David Peter <mail@david-peter.de>
Date: Wed, 7 Oct 2026 22:44:36 +0200
Subject: [PATCH] Add migration guidance for removed --reference option

---
 src/cli.rs                 | 13 +++++++++++++
 tests/integration_tests.rs | 19 +++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/src/cli.rs b/src/cli.rs
index e05bbdf..b01a894 100644
--- a/src/cli.rs
+++ b/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")
diff --git a/tests/integration_tests.rs b/tests/integration_tests.rs
index ce86ced..7b7cc2f 100644
--- a/tests/integration_tests.rs
+++ b/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()