From 738f6aa697f1beccc77aee2c718edbb3c73eef05 Mon Sep 17 00:00:00 2001
From: Daniel Samson <12231216+daniel-samson@users.noreply.github.com>
Date: Mon, 13 Jul 2026 05:15:56 +0100
Subject: [PATCH] Make sort-lines-group-by-start.sh a runnable script

It was a bare awk snippet starting with `|`, meant to be pasted into a
pipeline. Turn it into an executable script that takes the log file as an
argument (tools/sort-lines-group-by-start.sh filename.log) and document its
behaviour and usage in a header comment.
---
 tools/sort-lines-group-by-start.sh | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100755 tools/sort-lines-group-by-start.sh

diff --git a/tools/sort-lines-group-by-start.sh b/tools/sort-lines-group-by-start.sh
new file mode 100755
index 0000000..7efb099
--- /dev/null
+++ b/tools/sort-lines-group-by-start.sh
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+#
+# sort-lines-group-by-start — cluster lines that share their first
+# whitespace-separated field ($1). Keys appear in first-seen order, and lines
+# within a key keep their original order. It groups; it does NOT sort.
+#
+# Pass the log file as an argument; result is written to stdout:
+#
+#     tools/sort-lines-group-by-start.sh filename.log
+#
+# Useful for a serial/boot log where several sources interleave and each line is
+# prefixed with its source (the first field): this pulls every source's lines
+# back together, in the order the sources first appeared, without reordering
+# within a source.
+#
+#     input                       output
+#     pci-bus: scan start         pci-bus: scan start
+#     acpi: reported PNP0303      pci-bus: 5 functions
+#     pci-bus: 5 functions        acpi: reported PNP0303
+#     acpi: reported PNP0501      acpi: reported PNP0501
+
+awk '{lines[$1] = lines[$1] ? lines[$1] ORS $0 : $0; if (!seen[$1]++) order[++count] = $1} END {for (i=1; i<=count; i++) print lines[order[i]]}' "$@"