From 1ca4dc4c714a6cd28480899561f14f8b1f436235 Mon Sep 17 00:00:00 2001
From: Christoph Witzko <github@christophwitzko.com>
Date: Sat, 14 Jan 2023 17:57:25 +0100
Subject: [PATCH] docs: explain format commit template

---
 README.md | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e60f25c..0280358 100644
--- a/README.md
+++ b/README.md
@@ -21,12 +21,43 @@ The changelog generator will order the types of commits in the changelog in the
 - Build
 - CI
 
-## Emoji changelogs
+## Emoji Changelogs
 
 In order to use emoji changelogs including a prefixed emoji, you need to provide the following config when calling semantic-relase: `--changelog-generator-opt "emojis=true"`. Or add the config within your `.semrelrc` file.
 
 [Example Change Log](./examples/GENERATED_CHANGELOG.md)
 
+
+## Format Commit Template
+
+The plugin allows to specify the template which is used to render commits with the `--changelog-generator-opt` CLI flag, e.g., `--changelog-generator-opt "format_commit_template={{.Message}}"`. Or by adding the `format_commit_template` option within your `.semrelrc` file.
+
+
+The following variables are available:
+
+| Variable     | Description                                                                             |
+|--------------|-----------------------------------------------------------------------------------------|
+| .SHA         | The commit SHA (e.g., c862ecee7682be648289579b515dbc03a5357c89).                        |
+| .Type        | The type of the commit (e.g., feat, fix, chore, etc).                                   |
+| .Scope       | The scope of the commit.                                                                |
+| .Message     | The first line of the commit message.                                                   |
+| .Raw         | The raw commit message as a string array representing each line of the commit.          |
+| .Annotations | A map containing different commit annotations like the `author_name` or `author_email`. |
+
+Additionally, the following functions are available:
+
+| Function | Description                                     |
+|----------|-------------------------------------------------|
+| trimSHA  | Trims the SHA to the its first eight characters |
+
+### Examples:
+
+| Template                                                                                                                                       | Example Output                                             |
+|------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|
+| `* {{with .Scope -}} **{{.}}:** {{end}} {{- .Message}} ({{trimSHA .SHA}})`                                                                     | `* **app:** commit message (12345678)`                     |
+| `* {{with .Scope -}} **{{.}}:** {{end}} {{- .Message}} ({{trimSHA .SHA}}) {{- with index .Annotations "author_login" }} - by @{{.}} {{- end}}` | `* **app:** commit message (12345678) - by @commit-author` |
+
+
 ## Licence
 
 The [MIT License (MIT)](http://opensource.org/licenses/MIT)