**git-cliff** can generate [changelog](https://en.wikipedia.org/wiki/Changelog) files from the [Git](https://git-scm.com/) history by utilizing [conventional commits](#conventional_commits) as well as regex-powered [custom parsers](#commit_parsers). The [changelog template](#templating) can be customized with a [configuration file](#configuration-file) to match the desired format.
If you are using Arch Linux, [git-cliff](https://aur.archlinux.org/packages/git-cliff/) can be installed from the [AUR](https://aur.archlinux.org/) using an [AUR helper](https://wiki.archlinux.org/title/AUR_helpers):
Also, see the [release script](./release.sh) of this project which sets the changelog as a message of an annotated tag.
## Docker
The easiest way of running **git-cliff** (in the git root directory with [configuration file](#configuration-file) present) is to use the [available tags](https://hub.docker.com/repository/docker/orhunp/git-cliff/tags) from [Docker Hub](https://hub.docker.com/repository/docker/orhunp/git-cliff):
```sh
docker run -t -v "$(pwd)":/app/ orhunp/git-cliff:latest
```
Or you can use the image from the [GitHub Package Registry](https://github.com/orhun/git-cliff/packages/841947):
```sh
docker run -t -v "$(pwd)":/app/ docker.pkg.github.com/orhun/git-cliff/git-cliff:latest
```
Also, you can build the image yourself using `docker build -t git-cliff .` command.
## GitHub Action
It is possible to generate changelogs using [GitHub Actions](https://docs.github.com/en/actions) via [git-cliff-action](https://github.com/orhun/git-cliff-action).
```yml
- name: Generate a changelog
uses: orhun/git-cliff-action@v1
with:
config: cliff.toml
args: --verbose
env:
OUTPUT: CHANGELOG.md
```
See the [repository](https://github.com/orhun/git-cliff-action) for other [examples](https://github.com/orhun/git-cliff-action#examples).
Also, see the [continuous deployment workflow](./.github/workflows/cd.yml) of this project which sets the release notes for GitHub releases using this action.
This section contains the configuration options for changelog generation.
```toml
[changelog]
header = "Changelog"
body = """
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | upper_first }}
{% endfor %}
{% endfor %}
"""
trim = true
footer = "<!-- generated by git-cliff -->"
```
#### header
Header text that will be added to the beginning of the changelog.
#### body
Body template that represents a single release in the changelog.
See [templating](#templating) for more detail.
#### trim
If set to `true`, leading and trailing whitespaces are removed from the [body](#body).
It is useful for adding indentation to the template for readability, as shown [in the example](#changelog).
#### footer
Footer text that will be added to the end of the changelog.
### git
This section contains the parsing and git related configuration options.
```toml
[git]
conventional_commits = true
commit_parsers = [
{ message = "^feat*", group = "Features"},
{ message = "^fix*", group = "Bug Fixes"},
{ message = "^doc*", group = "Documentation"},
{ message = "^perf*", group = "Performance"},
{ message = "^refactor*", group = "Refactor"},
{ message = "^style*", group = "Styling"},
{ message = "^test*", group = "Testing"},
]
filter_commits = false
tag_pattern = "v[0-9]*"
skip_tags = "v0.1.0-beta.1"
```
#### conventional_commits
If set to `true`, parses the commits according to the [Conventional Commits specifications](https://www.conventionalcommits.org).
> The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.
> The commit message should be structured as follows:
```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
e.g. `feat(parser): add ability to parse arrays`
#### commit_parsers
An array of commit parsers for determining the commit groups by using regex.
Examples:
-`{ message = "^feat*", group = "Features"}`
- Group the commit as "Features" if the commit message (description) starts with "feat".
-`{ body = ".*security", group = "Security"}`
- Group the commit as "Security" if the commit body contains "security".
-`{ message = ".*deprecated", body = ".*deprecated", group = "Deprecation"}`
- Group the commit as "Deprecation" if the commit body and message contains "deprecated".
-`{ message = "^revert*", skip = true}`
- Skip processing the commit if the commit message (description) starts with "revert".
If set to `true`, commits that are not matched by [commit parsers](#commit_parsers) are filtered out.
#### tag_pattern
A glob pattern for matching the git tags.
e.g. It processes the same tags as the output of the following git command:
```sh
git tag --list 'v[0-9]*'
```
#### skip_tags
A regex for skip processing the matched tags.
## Templating
A template is a text where variables and expressions get replaced with values when it is rendered.
### Context
Context is the model that holds the required data for a template rendering. The [JSON](https://en.wikipedia.org/wiki/JSON) format is used in the following examples for the representation of a context.
#### Conventional Commits
> conventional_commits = **true**
For a [conventional commit](#conventional_commits) like this,
`breaking` flag is set to `true` when the commit has an exclamation mark after the commit type and scope, e.g.:
```
feat(scope)!: this is a breaking change
```
Or when the `BREAKING CHANGE:` footer is defined:
```
feat: add xyz
BREAKING CHANGE: this is a breaking change
```
`breaking_description` is set to the explanation of the breaking change. This description is expected to be present in the `BREAKING CHANGE` footer. However, if it's not provided, the `message` is expected to describe the breaking change.
If [conventional_commits](#conventional_commits) is set to `false`, then some of the fields are omitted from the context or squashed into the `message` field:
**git-cliff** uses [Tera](https://github.com/Keats/tera) as the template engine. It has a syntax based on [Jinja2](http://jinja.pocoo.org/) and [Django](https://docs.djangoproject.com/en/3.1/topics/templates/) templates.
See the [Tera Documentation](https://tera.netlify.app/docs/#templates) for more information about [control structures](https://tera.netlify.app/docs/#control-structures), [built-ins filters](https://tera.netlify.app/docs/#built-ins), etc.
Custom built-in filters that **git-cliff** uses:
-`upper_first`: Converts the first character of a string to uppercase.
