From eecaf6c4b9b5c6c248302e7db2bb15b7ca1c6b29 Mon Sep 17 00:00:00 2001
From: Dennis Fink
Date: Sun, 10 May 2026 20:37:01 +0200
Subject: feat(preset): add --list-presets to enumerate available presets

Print all *.sh files found in $PRESET_DIR, one per line, with a one-line
description extracted from the first line of each file if it matches a
`# description: …` comment. Presets without such a comment are listed
without a description.

Symlinks pointing to another preset inside $PRESET_DIR are shown as
"<name> - Symlinked to <target>" rather than duplicating the
description. Symlinks pointing outside $PRESET_DIR are followed and
treated as regular preset files.

Column width for preset names is calculated from the longest name in the
directory so descriptions align with minimal padding.

Also extracts the repeated readlink/realpath idiom into a dedicated
resolve_path() helper and adds a doc comment to filesize().

Exits immediately after printing (same pattern as --version/--help).
Honours --quiet/NO_COLOR via the existing msg() and color
infrastructure.
---
 README.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index a3adaf4..8ce5e12 100644
--- a/README.md
+++ b/README.md
@@ -110,6 +110,21 @@ ffargs=(
 > **Security:** presets are executed as shell code. Only use presets from
 > trusted sources.
 
+A preset may carry an optional one-line description as a shell comment:
+
+```sh
+# description: Encode to AV1 with SVT-AV1 at a balanced quality/speed trade-off
+ffargs=(
+    -c:v:0 libsvtav1
+    -crf 30
+    -preset 6
+    -pix_fmt "$output_pixel_format"
+)
+```
+
+Run `transcode.sh --list-presets` to enumerate all presets in the preset
+directory and display their descriptions.
+
 ### Configuration file
 
 An optional TOML configuration file can be placed at:
@@ -194,6 +209,7 @@ transcode.sh [OPTION] [--] FILE...
 | `-v`, `--verbose` | More detailed output |
 | `--color` / `--no-color` | Force or disable colored output |
 | `--version` | Print version information |
+| `--list-presets` | List available presets (name + description) and exit |
 | `-h`, `-?`, `--help` | Show help and exit |
 
 ### Examples
-- 
cgit v1.3.1