Further simplifications

Fixes: #781

Expose the `$HYPERFINE_ITERATION` variable to intermediate commands.
This will allow iteration-specific prepare/conclude, such as:

```bash
hyperfine --runs 5 --prepare 'echo touch file${HYPERFINE_ITERATION}.dat' \
    'echo testing file${HYPERFINE_ITERATION}.dat' \
    --conclude 'echo rm file${HYPERFINE_ITERATION}.dat' --show-output
```

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/executor.rs

@@ -15,6 +15,7 @@ use super::measurement::{Measurement, Measurements};
 
 use anyhow::{bail, Context, Result};
 
+#[derive(Clone, Copy)]
 pub enum BenchmarkIteration {
     NonBenchmarkRun,
     Warmup(u64),

src/benchmark/mod.rs

@@ -58,11 +58,12 @@ impl<'a> Benchmark<'a> {
         command: &Command<'_>,
         error_output: &'static str,
         output_policy: &CommandOutputPolicy,
+        iteration: executor::BenchmarkIteration,
     ) -> Result<Measurement> {
         self.executor
             .run_command_and_measure(
                 command,
-                executor::BenchmarkIteration::NonBenchmarkRun,
+                iteration,
                 Some(CmdFailureAction::RaiseError),
                 output_policy,
             )
@@ -85,7 +86,14 @@ impl<'a> Benchmark<'a> {
                             Append ' || true' to the command if you are sure that this can be ignored.";
 
         Ok(command
-            .map(|cmd| self.run_intermediate_command(&cmd, error_output, output_policy))
+            .map(|cmd| {
+                self.run_intermediate_command(
+                    &cmd,
+                    error_output,
+                    output_policy,
+                    BenchmarkIteration::NonBenchmarkRun,
+                )
+            })
             .transpose()?
             .unwrap_or_default())
     }
@@ -106,7 +114,14 @@ impl<'a> Benchmark<'a> {
                             Append ' || true' to the command if you are sure that this can be ignored.";
 
         Ok(command
-            .map(|cmd| self.run_intermediate_command(&cmd, error_output, output_policy))
+            .map(|cmd| {
+                self.run_intermediate_command(
+                    &cmd,
+                    error_output,
+                    output_policy,
+                    BenchmarkIteration::NonBenchmarkRun,
+                )
+            })
             .transpose()?
             .unwrap_or_default())
     }
@@ -116,11 +131,12 @@ impl<'a> Benchmark<'a> {
         &self,
         command: &Command<'_>,
         output_policy: &CommandOutputPolicy,
+        iteration: executor::BenchmarkIteration,
     ) -> Result<Measurement> {
         let error_output = "The preparation command terminated with a non-zero exit code. \
                             Append ' || true' to the command if you are sure that this can be ignored.";
 
-        self.run_intermediate_command(command, error_output, output_policy)
+        self.run_intermediate_command(command, error_output, output_policy, iteration)
     }
 
     /// Run the command specified by `--conclude`.
@@ -128,11 +144,12 @@ impl<'a> Benchmark<'a> {
         &self,
         command: &Command<'_>,
         output_policy: &CommandOutputPolicy,
+        iteration: executor::BenchmarkIteration,
     ) -> Result<Measurement> {
         let error_output = "The conclusion command terminated with a non-zero exit code. \
                             Append ' || true' to the command if you are sure that this can be ignored.";
 
-        self.run_intermediate_command(command, error_output, output_policy)
+        self.run_intermediate_command(command, error_output, output_policy, iteration)
     }
 
     /// Run the benchmark for a single command
@@ -165,10 +182,10 @@ impl<'a> Benchmark<'a> {
             )
         });
 
-        let run_preparation_command = || {
+        let run_preparation_command = |iteration: executor::BenchmarkIteration| {
             preparation_command
                 .as_ref()
-                .map(|cmd| self.run_preparation_command(cmd, output_policy))
+                .map(|cmd| self.run_preparation_command(cmd, output_policy, iteration))
                 .transpose()
         };
 
@@ -184,10 +201,10 @@ impl<'a> Benchmark<'a> {
                 self.command.get_parameters().iter().cloned(),
             )
         });
-        let run_conclusion_command = || {
+        let run_conclusion_command = |iteration: executor::BenchmarkIteration| {
             conclusion_command
                 .as_ref()
-                .map(|cmd| self.run_conclusion_command(cmd, output_policy))
+                .map(|cmd| self.run_conclusion_command(cmd, output_policy, iteration))
                 .transpose()
         };
 
@@ -206,14 +223,15 @@ impl<'a> Benchmark<'a> {
             };
 
             for i in 0..self.options.warmup_count {
-                let _ = run_preparation_command()?;
+                let warmup_iteration = BenchmarkIteration::Warmup(i);
+                let _ = run_preparation_command(warmup_iteration)?;
                 let _ = self.executor.run_command_and_measure(
                     self.command,
-                    BenchmarkIteration::Warmup(i),
+                    warmup_iteration,
                     None,
                     output_policy,
                 )?;
-                let _ = run_conclusion_command()?;
+                let _ = run_conclusion_command(warmup_iteration)?;
                 if let Some(bar) = progress_bar.as_ref() {
                     bar.inc(1)
                 }
@@ -234,7 +252,8 @@ impl<'a> Benchmark<'a> {
             None
         };
 
-        let preparation_result = run_preparation_command()?;
+        let benchmark_iteration = BenchmarkIteration::Benchmark(0);
+        let preparation_result = run_preparation_command(benchmark_iteration)?;
         let preparation_overhead = preparation_result.map_or(Time::zero(), |res| {
             res.time_wall_clock + self.executor.time_overhead()
         });
@@ -242,13 +261,13 @@ impl<'a> Benchmark<'a> {
         // Initial timing run
         let res = self.executor.run_command_and_measure(
             self.command,
-            BenchmarkIteration::Benchmark(0),
+            benchmark_iteration,
             None,
             output_policy,
         )?;
         let success = res.exit_status.success();
 
-        let conclusion_result = run_conclusion_command()?;
+        let conclusion_result = run_conclusion_command(benchmark_iteration)?;
         let conclusion_overhead = conclusion_result.map_or(Time::zero(), |res| {
             res.time_wall_clock + self.executor.time_overhead()
         });
@@ -289,7 +308,8 @@ impl<'a> Benchmark<'a> {
 
         // Gather statistics (perform the actual benchmark)
         for i in 0..count_remaining {
-            run_preparation_command()?;
+            let benchmark_iteration = BenchmarkIteration::Benchmark(i + 1);
+            run_preparation_command(benchmark_iteration)?;
 
             let msg = {
                 let t_wall_clock_mean = measurements.time_wall_clock_mean();
@@ -307,7 +327,7 @@ impl<'a> Benchmark<'a> {
 
             let res = self.executor.run_command_and_measure(
                 self.command,
-                BenchmarkIteration::Benchmark(i + 1),
+                benchmark_iteration,
                 None,
                 output_policy,
             )?;
@@ -321,7 +341,7 @@ impl<'a> Benchmark<'a> {
                 bar.inc(1)
             }
 
-            run_conclusion_command()?;
+            run_conclusion_command(benchmark_iteration)?;
         }
 
         if let Some(bar) = progress_bar.as_ref() {

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/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()
@@ -1016,3 +1037,45 @@ fn windows_quote_before_quote_args() {
         .assert()
         .success();
 }
+
+#[test]
+fn hyperfine_iteration_env_var_in_prepare_and_conclude_commands() {
+    let tempdir = tempfile::tempdir().unwrap();
+    let output_path = tempdir.path().join("iteration output.txt");
+    let iteration = if cfg!(windows) {
+        "%HYPERFINE_ITERATION%"
+    } else {
+        "$HYPERFINE_ITERATION"
+    };
+    let command = |phase| format!(r#"echo {phase}:{iteration} >> "iteration output.txt""#);
+
+    hyperfine()
+        .current_dir(tempdir.path())
+        .arg("--runs=2")
+        .arg("--warmup=1")
+        .arg("--prepare")
+        .arg(command("prepare"))
+        .arg(command("benchmark"))
+        .arg("--conclude")
+        .arg(command("conclude"))
+        .assert()
+        .success();
+
+    let contents = std::fs::read_to_string(output_path).unwrap();
+    // cmd.exe's echo includes the space before the redirection operator.
+    let lines: Vec<&str> = contents.lines().map(str::trim_end).collect();
+    assert_eq!(
+        lines,
+        [
+            "prepare:warmup-0",
+            "benchmark:warmup-0",
+            "conclude:warmup-0",
+            "prepare:0",
+            "benchmark:0",
+            "conclude:0",
+            "prepare:1",
+            "benchmark:1",
+            "conclude:1",
+        ]
+    );
+}