Store parameter usage metadata in benchmark results

Add colors to --help/-h

README.md

@@ -88,6 +88,22 @@ option:
 hyperfine -L compiler g++,clang++ '{compiler} -O2 main.cpp'
 ```
 
+A common use case is comparing the same command across multiple Git branches. Use `--setup`
+to switch branches once before each set of timing runs, so the branch switch is not part of
+the measured command:
+```sh
+hyperfine \
+    --parameter-list branch main,performance-improvements \
+    --setup 'git switch {branch}' \
+    'python main.py'
+```
+
+If you need a unique value for each individual run of a benchmark command, hyperfine also exposes
+the zero-based `$HYPERFINE_ITERATION` environment variable inside the benchmarked command itself:
+```sh
+hyperfine 'my-command > output-${HYPERFINE_ITERATION}.log'
+```
+
 ### Intermediate shell
 
 By default, commands are executed using `sh` on Unix (resolved through `PATH`) or `cmd.exe` on Windows.

src/benchmark/benchmark_result.rs

@@ -2,6 +2,15 @@ use std::collections::BTreeMap;
 
 use serde::Serialize;
 
+/// Parameter value and whether it was used in the command line template
+#[derive(Debug, Default, Clone, Serialize, PartialEq)]
+#[serde(transparent)]
+pub struct Parameter {
+    pub value: String,
+    #[serde(skip)]
+    pub is_unused: bool,
+}
+
 /// Set of values that will be exported.
 // NOTE: `serde` is used for JSON serialization, but not for CSV serialization due to the
 // `parameters` map. Update `src/hyperfine/export/csv.rs` with new fields, as appropriate.
@@ -49,5 +58,5 @@ pub struct BenchmarkResult {
 
     /// Parameter values for this benchmark
     #[serde(skip_serializing_if = "BTreeMap::is_empty")]
-    pub parameters: BTreeMap<String, String>,
+    pub parameters: BTreeMap<String, Parameter>,
 }

src/benchmark/mod.rs

@@ -19,7 +19,7 @@ use crate::output::warnings::{OutlierWarningOptions, Warnings};
 use crate::parameter::ParameterNameAndValue;
 use crate::quantity::{byte, const_time_from_seconds, ratio, second, FormatQuantity, Time, Zero};
 use crate::util::exit_code::extract_exit_code;
-use benchmark_result::BenchmarkResult;
+use benchmark_result::{BenchmarkResult, Parameter};
 use measurement::{Measurement, Measurements};
 
 use anyhow::{anyhow, Result};
@@ -474,7 +474,15 @@ impl<'a> Benchmark<'a> {
                 .command
                 .get_parameters()
                 .iter()
-                .map(|(name, value)| (name.to_string(), value.to_string()))
+                .map(|(name, value)| {
+                    (
+                        name.to_string(),
+                        Parameter {
+                            value: value.to_string(),
+                            is_unused: self.command.is_parameter_unused(name),
+                        },
+                    )
+                })
                 .collect(),
         })
     }

src/cli.rs

@@ -1,8 +1,10 @@
 use std::ffi::OsString;
 
 use clap::{
-    builder::NonEmptyStringValueParser, crate_version, Arg, ArgAction, ArgMatches, Command,
-    ValueHint,
+    builder::styling::{AnsiColor, Effects},
+    builder::NonEmptyStringValueParser,
+    builder::Styles,
+    crate_version, Arg, ArgAction, ArgMatches, Command, ValueHint,
 };
 
 pub fn get_cli_arguments<'a, I, T>(args: I) -> ArgMatches
@@ -14,10 +16,17 @@ where
     command.get_matches_from(args)
 }
 
+const STYLES: Styles = Styles::styled()
+    .header(AnsiColor::Green.on_default().effects(Effects::BOLD))
+    .usage(AnsiColor::Green.on_default().effects(Effects::BOLD))
+    .literal(AnsiColor::Cyan.on_default().effects(Effects::BOLD))
+    .placeholder(AnsiColor::Cyan.on_default());
+
 /// Build the clap command for parsing command line arguments
 fn build_command() -> Command {
     Command::new("hyperfine")
         .version(crate_version!())
+        .styles(STYLES)
         .next_line_help(true)
         .hide_possible_values(true)
         .about("A command-line benchmarking tool.")

src/export/csv.rs

@@ -53,7 +53,7 @@ impl Exporter for CsvExporter {
                 fields.push(Cow::Owned(format!("{f:.CSV_PRECISION$}").into_bytes()))
             }
             for v in res.parameters.values() {
-                fields.push(Cow::Borrowed(v.as_bytes()))
+                fields.push(Cow::Borrowed(v.value.as_bytes()))
             }
             writer.write_record(fields)?;
         }
@@ -64,6 +64,7 @@ impl Exporter for CsvExporter {
 
 #[test]
 fn test_csv() {
+    use crate::benchmark::benchmark_result::Parameter;
     use std::collections::BTreeMap;
     let exporter = CsvExporter::default();
 
@@ -83,8 +84,20 @@ fn test_csv() {
             exit_codes: vec![Some(0), Some(0), Some(0)],
             parameters: {
                 let mut params = BTreeMap::new();
-                params.insert("foo".into(), "one".into());
-                params.insert("bar".into(), "two".into());
+                params.insert(
+                    "foo".into(),
+                    Parameter {
+                        value: "one".into(),
+                        is_unused: false,
+                    },
+                );
+                params.insert(
+                    "bar".into(),
+                    Parameter {
+                        value: "two".into(),
+                        is_unused: false,
+                    },
+                );
                 params
             },
         },
@@ -103,8 +116,20 @@ fn test_csv() {
             exit_codes: vec![Some(0), Some(0), Some(0)],
             parameters: {
                 let mut params = BTreeMap::new();
-                params.insert("foo".into(), "one".into());
-                params.insert("bar".into(), "seven".into());
+                params.insert(
+                    "foo".into(),
+                    Parameter {
+                        value: "one".into(),
+                        is_unused: false,
+                    },
+                );
+                params.insert(
+                    "bar".into(),
+                    Parameter {
+                        value: "seven".into(),
+                        is_unused: false,
+                    },
+                );
                 params
             },
         },

src/export/markdown.rs

@@ -24,7 +24,19 @@ impl MarkupExporter for MarkdownExporter {
     }
 
     fn command(&self, cmd: &str) -> String {
-        format!("`{cmd}`")
+        let longest_backtick_run = cmd
+            .split(|character| character != '`')
+            .map(str::len)
+            .max()
+            .unwrap_or(0);
+
+        if longest_backtick_run == 0 {
+            format!("`{cmd}`")
+        } else {
+            // Use a longer delimiter and keep command backticks separate from it.
+            let delimiter = "`".repeat(longest_backtick_run + 1);
+            format!("{delimiter} {cmd} {delimiter}")
+        }
     }
 }
 
@@ -44,3 +56,19 @@ fn test_markdown_formatter_table_divider() {
     let divider = formatter.table_divider(&[Alignment::Left, Alignment::Right, Alignment::Left]);
     assert_eq!(divider, "|:---|---:|:---|\n");
 }
+
+#[test]
+fn test_markdown_formatter_command_with_backticks() {
+    let formatter = MarkdownExporter::default();
+
+    for (command, expected) in [
+        ("echo `uname`", "`` echo `uname` ``"),
+        ("echo ``quoted``", "``` echo ``quoted`` ```"),
+        ("`` `quoted` ``", "``` `` `quoted` `` ```"),
+        ("`", "`` ` ``"),
+        ("echo ```", "```` echo ``` ````"),
+        (" echo `uname` ", "``  echo `uname`  ``"),
+    ] {
+        assert_eq!(formatter.command(command), expected, "{command:?}");
+    }
+}

src/quantity/statistics.rs

@@ -106,7 +106,7 @@ pub fn standard_deviation<Q: UnsafeRawValue>(values: &[Q], mean: Q) -> Q {
     Q::unsafe_from_raw_value((sum / (values.len() as f64 - 1.0)).sqrt())
 }
 
-/// Compute modifized Z-scores for a given sample. A (unmodified) Z-score is defined by
+/// Compute modified Z-scores for a given sample. A (unmodified) Z-score is defined by
 /// `(x_i - x_mean)/x_stddev` whereas the modified Z-score is defined by `(x_i - x_median)/MAD`
 /// where MAD is the median absolute deviation.
 ///

tests/integration_tests.rs

@@ -929,6 +929,27 @@ fn invalid_command_options_preserve_export_files() {
     }
 }
 
+#[test]
+fn markdown_export_preserves_backticks_and_pipes_in_command_names() {
+    let _settings = snapshot_settings().bind_to_scope();
+    assert_cmd_snapshot!(hyperfine_debug()
+        .arg("--style=none")
+        .arg("--export-markdown=-")
+        .arg("--command-name=echo `uname` | cat")
+        .arg("sleep 1"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    | Command | Mean [s] | Min [s] | Max [s] | Relative |
+    |:---|---:|---:|---:|---:|
+    | `` echo `uname` \| cat `` | 1.000 ± 0.000 | 1.000 | 1.000 | 1.00 |
+
+
+    ----- stderr -----
+    ");
+}
+
 #[test]
 fn unused_parameters_are_shown_in_benchmark_name() {
     hyperfine()