docs(run.sh): update script documentation and help output

- Improve script documentation for clarity and consistency
- Extend help output to include detailed descriptions of options

run.sh

@@ -1,12 +1,10 @@
 #!/usr/bin/env bash
 # run.sh – local wrapper for the “deb-changelog-action”
 #
-# This script
+# Behaviour:
-#   1. clones https://git.0xmax42.io/actions/deb-changelog-action at the
+#   • Clones https://git.0xmax42.io/actions/deb-changelog-action at the requested version into a temporary directory.
-#      requested version into a temporary directory,
+#   • Installs git-cliff via the action’s helper script.
-#   2. installs git-cliff using the action’s helper script, and
+#   • Generates a Debian-style changelog **in the current working directory** via the action’s generator script.
-#   3. generates a Debian-style changelog **in the current working directory**
-#      via the action’s generator script.
 #
 # Usage:
 #   ./run.sh --version v0 \
@@ -17,6 +15,16 @@
 #            [--output_file debian/changelog] \
 #            [--cliff_config path/to/cliff.toml]
 #
+# Options:
+#   --version <ver>        Action version to clone (required)
+#   --tag <tag>            Git tag used as starting point (required)
+#   --package_name <name>  Debian package name (required)
+#   --author_name <name>   Changelog author name (required)
+#   --author_email <mail>  Changelog author e-mail (required)
+#   --output_file <file>   Changelog path (default: debian/changelog)
+#   --cliff_config <file>  git-cliff config file (default: configs/cliff.debian.toml)
+#   -h, --help             Show this help message
+#
 # Notes:
 #   • Paths given for --output_file are interpreted relative to the directory
 #     where you run this script.
@@ -38,7 +46,7 @@ OUTPUT_FILE="debian/changelog"
 CLIFF_CONFIG=""
 # ───────────────────────────────────────────────
 
-show_help() { sed -n '2,25p' "$0"; }
+show_help() { sed -n '2,34p' "$0"; }
 
 # 1 ─ Parse CLI options ─────────────────────────
 while [[ $# -gt 0 ]]; do

scripts/install-git-cliff.sh

@@ -1,17 +1,27 @@
 #!/usr/bin/env bash
-# install-git-cliff.sh – fetches the latest or specified git-cliff binary
+# install-git-cliff.sh – Installs the git-cliff binary
-# Usage (back-compatible):
+
-#   sudo ./install-git-cliff.sh                          # latest version, default arch/dir
+# Usage:
-#   sudo ./install-git-cliff.sh 2.9.1                    # specific version
+#   sudo ./install-git-cliff.sh [options] [<version>]
-# Extended options:
+
-#   sudo ./install-git-cliff.sh -a x86_64-linux-musl [<ver>]   # custom arch
+# Options:
-#   sudo ./install-git-cliff.sh -d /opt/tools [<ver>]          # custom install dir
+#   -a, --arch <triplet>   Target architecture (default: ${DEFAULT_ARCH_DISPLAY})
-#   sudo ./install-git-cliff.sh -n [<ver>]                     # dry-run (no install)
+#   -d, --dir  <path>      Installation directory (default: ${INSTALL_DIR_DEFAULT})
-#   sudo ./install-git-cliff.sh -h | --help                    # help
+#   -n, --dry-run          Download and verify, but do NOT install
-#
+#   -h, --help             Show this help message
+
+# Arguments:
+#   <version>              git-cliff version to install (default: latest)
+
 # Behaviour:
-#   • If git-cliff is already in \$PATH and **no version** was requested, the script exits early.
+#   • If git-cliff is already in PATH and no version was requested the script exits.
-#   • If a specific version was requested, the installed version is compared; identical → exit, different → upgrade.
+#   • If a specific version was requested, the installed version is compared and
+#     only upgraded if it differs.
+
+# Supported architecture triplets (examples):
+#   aarch64-linux-gnu / musl / apple-darwin / pc-windows-msvc
+#   i686-linux-gnu / musl / pc-windows-msvc
+#   x86_64-linux-gnu / musl / apple-darwin / pc-windows-*
 set -euo pipefail
 
 REPO="orhun/git-cliff"
@@ -29,33 +39,7 @@ USER_VERSION_SPECIFIED=false
 # ───────────────────────────────────────────────
 
 # 0 Help function
-show_help() {
+show_help() { sed -n '2,24p' "$0"; }
-  cat <<EOF
-install-git-cliff.sh – Installs the git-cliff binary
-
-Usage:
-  sudo ./install-git-cliff.sh [options] [<version>]
-
-Options:
-  -a, --arch <triplet>   Target architecture (default: ${DEFAULT_ARCH_DISPLAY})
-  -d, --dir  <path>      Installation directory (default: ${INSTALL_DIR_DEFAULT})
-  -n, --dry-run          Download and verify, but do NOT install
-  -h, --help             Show this help message
-
-Arguments:
-  <version>              git-cliff version to install (default: latest)
-
-Behaviour:
-  • If git-cliff is already in PATH and no version was requested the script exits.
-  • If a specific version was requested, the installed version is compared and
-    only upgraded if it differs.
-
-Supported architecture triplets (examples):
-  aarch64-linux-gnu / musl / apple-darwin / pc-windows-msvc
-  i686-linux-gnu / musl / pc-windows-msvc
-  x86_64-linux-gnu / musl / apple-darwin / pc-windows-*
-EOF
-}
 
 # 1 Parse options (keeps old single-arg form)
 POSITIONAL=()