;dev: bin: commitlint: check for preferred style in commit messages

bin/commitlint

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2059
+#
+# Check git commits for compliance with hledger's conventions,
+# described at https://hledger.org/CONTRIBUTING.html#commit-messages.
+#
+# Usage:
+# commitlint [GITREV|GITRANGE]
+#   Checks unpushed commits, or the specified commit or range.
+#   If the argument contains - or .. it's a range, otherwise a single commit.
+#
+# Examples:
+# commitlint                              # unpushed commits
+# commitlint HEAD                         # last commit
+# commitlint d5d19f841                    # this commit
+# commitlint -20                          # last 20 commits
+# commitlint master..                     # commits in this branch
+# commitlint 1.21..1.22 | grep -F [FAIL]  # bad commits in 1.22 release cycle
+
+if [[ -n ${NO_COLOR+set} ]]
+then
+    RED=""
+    GRN=""
+    NRM=""
+else
+    RED="\033[31m"
+    GRN="\033[32m"
+    NRM="\033[0m"
+fi
+
+# checkcommit GITHASH - check this commit's message and print result
+function checkcommit()
+{
+    HASH=${1}
+    SUMMARY=$(git log -1 "$HASH" --pretty=format:"%s")
+
+    # Does the summary have a type: prefix ?
+    # Can begin with ; and/or end with !, some spaces are tolerated.
+    FMT="%s %-60s  %b${NRM}\n"
+    if ! echo "$SUMMARY" | grep -qE '^(; *)?\w+:[ \w]+!?'
+    then
+        printf "$FMT" "$HASH" "$SUMMARY" "${RED}[FAIL]"
+        STATUS=1
+    else
+        printf "$FMT" "$HASH" "$SUMMARY" "${GRN}[ok]"
+    fi
+}
+
+RANGE=${*:-"@{u}.."}  # @{u} = upstream
+
+if [[ ! $RANGE =~ (-|\.\.) ]]
+then
+    RANGE=$RANGE^!  # assume range is a single commit
+fi
+
+HASHES=$(git log --abbrev-commit --pretty=format:%h "$RANGE")
+
+STATUS=
+for HASH in $HASHES; do
+    checkcommit "$HASH"
+done
+
+if [[ -z $STATUS ]]
+then
+    printf "" # "${GRN}Ok${NRM}\n"
+else
+    printf "\n${RED}Some commits are not in preferred style.${NRM}\n"
+    cat <<EOF
+---------------------------------------------------------------------------
+Commit messages should follow this format:
+
+  [;]type[!]: [topic:] summary
+
+  [Optional description, ready for release notes/changelog.]
+
+Explanation:
+
+The subject line should have a type: prefix. Common types:
+ feat imp fix            - end-user changes (->release notes & changelogs)
+ cha pkg lib             - packager/builder/lib-user changes (->changelogs)
+ dev doc test ci ref cln - developer changes
+
+It may additionally have a topic prefix such as:
+ (see https://hledger.org/CONTRIBUTING.html#open-issues -> COMPONENT)
+
+Mention any related issues, usually parenthesised at end of summary: (#1234)
+! indicates a breaking change.
+; skips expensive CI tests.
+
+These conventions are evolving. In practice, any type or topic will
+do. Use your best judgement and we'll polish during code review.
+More detail: https://hledger.org/CONTRIBUTING.html#commit-messages
+---------------------------------------------------------------------------
+EOF
+
+fi
+
+exit 0"$STATUS"