From 81ecda64987173346c514c172e69b45834c87e6b Mon Sep 17 00:00:00 2001
From: Sylvestre Ledru <sylvestre@debian.org>
Date: Sat, 4 Oct 2025 13:09:25 +0200
Subject: [PATCH 1/2] Document the bench process

---
 docs/src/performance.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/docs/src/performance.md b/docs/src/performance.md
index 10c7b3834..5d25b0e5f 100644
--- a/docs/src/performance.md
+++ b/docs/src/performance.md
@@ -56,6 +56,47 @@ Hyperfine provides summary statistics including:
 
 Look for consistent patterns rather than focusing on individual runs, and be aware of system noise that might affect results.
 
+## Integrated Benchmarking
+
+Utilities include integrated benchmarks in `src/uu/*/benches/*` using [CodSpeed](https://codspeed.io/) and [Divan](https://github.com/nvzqz/divan).
+
+**Important**: Before starting performance optimization work, you should add a benchmark for the utility. This provides a baseline for measuring improvements and ensures changes have measurable impact.
+
+### Running Benchmarks
+
+```bash
+# Build and run benchmarks for a specific utility
+cargo codspeed build -p uu_expand
+cargo codspeed run -p uu_expand
+```
+
+### Writing Benchmarks
+
+Use common functions from `src/uucore/src/lib/features/benchmark.rs`:
+
+```rust
+use divan::{Bencher, black_box};
+use uu_expand::uumain;
+use uucore::benchmark::{create_test_file, run_util_function, text_data};
+
+#[divan::bench(args = [10_000, 100_000])]
+fn bench_expand(bencher: Bencher, num_lines: usize) {
+    let data = text_data::generate_ascii_data(num_lines);
+    let temp_dir = tempfile::tempdir().unwrap();
+    let file_path = create_test_file(&data, temp_dir.path());
+
+    bencher.bench(|| {
+        black_box(run_util_function(uumain, &[file_path.to_str().unwrap()]));
+    });
+}
+
+fn main() {
+    divan::main();
+}
+```
+
+Common helpers include `text_data::generate_*()` for test data and `fs_tree::create_*()` for directory structures.
+
 ## Using Samply for Profiling
 
 [Samply](https://github.com/mstange/samply) is a sampling profiler that helps you identify performance bottlenecks in your code.

From 8e7111784cb2976ab5069e04b7284f1fe45c873e Mon Sep 17 00:00:00 2001
From: Sylvestre Ledru <sylvestre@debian.org>
Date: Sat, 4 Oct 2025 17:24:55 +0200
Subject: [PATCH 2/2] add ignore usize to the spell list

---
 docs/src/performance.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/src/performance.md b/docs/src/performance.md
index 5d25b0e5f..e51ae6b95 100644
--- a/docs/src/performance.md
+++ b/docs/src/performance.md
@@ -1,4 +1,4 @@
-<!-- spell-checker:ignore taskset -->
+<!-- spell-checker:ignore taskset usize -->
 
 # Performance Profiling Tutorial