Add git-cliff example (#1176)

Author: anselmbradford

README.md

@@ -181,6 +181,7 @@ message conventions. Plugins are available for:
 - auto-changelog
 - Conventional Changelog
 - Keep A Changelog
+- git-cliff
 
 To print the changelog without releasing anything, add the `--changelog` flag.
 

docs/changelog.md

@@ -10,6 +10,7 @@ these commands output the changelog to `stdout`.
 - [auto-changelog][3]
 - [Conventional Changelog][4]
 - [Keep A Changelog][5]
+- [git-cliff][14]
 
 Some projects keep their changelog in e.g. `CHANGELOG.md` or `history.md`. To auto-update this file and include this in
 the release commit, the recommended configuration is to do this in the `after:bump` hook (see example below).
@@ -92,6 +93,14 @@ This plugin updates `CHANGELOG.md` file according to
 }
 ```
 
+## Git-cliff
+
+Git-cliff is a customizable changelog generator that follows
+Conventional Commit specifications. Similar to auto-changelog, it can be used
+as a companion to release-it.
+
+See the [git-cliff recipe][15] for an example setup.
+
 [1]: ../config/release-it.json
 [2]: #github-and-gitlab-releases
 [3]: #auto-changelog
@@ -105,3 +114,5 @@ This plugin updates `CHANGELOG.md` file according to
 [11]: https://github.com/release-it/conventional-changelog
 [12]: https://keepachangelog.com
 [13]: https://github.com/release-it/keep-a-changelog
+[14]: https://github.com/orhun/git-cliff
+[15]: ./recipes/git-cliff.md

docs/recipes/git-cliff.md

@@ -0,0 +1,59 @@
+# Git-cliff
+
+Please refer to [git-cliff documentation][1] for more details and usage.
+
+## Config
+
+Add git-cliff to the project:
+
+```bash
+npm install --save-dev git-cliff
+```
+
+Git-cliff has the ability to use the Conventional Commits convention
+to automatically set the package version.
+Release-it allows the user to select the version that should be released.
+Therefore, it may be helpful to generate the changelog from the version in the
+`package.json` that was bumped by release-it.
+
+```sh
+#!/usr/bin/env bash
+
+NODE_VERSION=$(node -p -e "require('./package.json').version")
+
+if [ "$1" = "stdout" ]; then
+    npm exec git-cliff -o - --unreleased --tag $NODE_VERSION
+else
+    npm exec git-cliff -o './CHANGELOG.md' --tag $NODE_VERSION
+fi
+```
+
+Example configuration in the release-it config:
+
+```json
+{
+  "hooks": {
+    "after:bump": "./changelog.sh"
+  },
+  "github": {
+    "releaseNotes": "./changelog.sh stdout"
+  }
+}
+```
+
+## Template
+
+Git-cliff uses Tera as a templating language, which is inspired by Jinja2 and
+Django templates.
+
+See [git-cliff syntax docs][2] for more information.
+
+## Monorepos
+
+Git-cliff has a `--include-path` flag to scope changes to a specific directory path.
+
+See [git-cliff monorepo docs][3] for more information.
+
+[1]: https://github.com/orhun/git-cliff
+[2]: https://git-cliff.org/docs/templating/examples
+[3]: https://git-cliff.org/docs/usage/monorepos