Skip to main content

changelog

This section contains the configuration options for changelog generation.

Example​

[changelog]
header = "Changelog"
header_marker = "<!-- git-cliff: end of header -->"
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 -->"
postprocessors = [{ pattern = "foo", replace = "bar"}]

See templating for more detail.

Header template that will be rendered and added to the beginning of the changelog.

The template context contains the full list of releases in the variable releases. See templating for more details.

header_marker​

A stable marker written after a header that uses template variables. When prepending releases with --prepend, git-cliff uses this marker to remove the previously rendered header even if its content has changed.

[changelog]
header_marker = "<!-- git-cliff: end of header -->"

Static headers continue to be matched by their configured text and do not emit the marker. Set it to an empty string to disable the marker.

body​

Body template that will be rendered for each release in the changelog. For example, if the changelog contains 3 releases, it will be rendered 3 times, once for each release.

The template context contains one release in the variable release. See templating for more detail.

Footer template that will be rendered and added to the end of the changelog.

The template context contains the full list of releases in the variable releases. See templating for more details.

See Keep a Changelog configuration for seeing the example of adding links to the end of the changelog.

trim​

If set to true, leading and trailing whitespace are removed from the body.

It is useful for adding indentation to the template for readability, as shown in the example.

render_always​

If set to true, the changelog body will be rendered even if there are no releases to process.

format​

If set to true, the rendered changelog is passed through a Markdown formatter before it is written. This normalizes heading styles, list markers, and blank lines so you don't have to fight the template with {%- and trim to get tidy output.

Formatting only runs when the output is Markdown, i.e. writing to stdout or to a file with a .md extension. It is off by default, and with it off the output is exactly what the templates render.

[changelog]
format = true
note

This is an out-of-the-box alternative to configuring postprocessors with an external tool like mdformat, e.g.:

[changelog]
postprocessors = [
  { pattern = '.*', replace_command = 'mdformat -' },
]

postprocessors​

An array of commit postprocessors for manipulating the changelog before outputting. Can e.g. be used for replacing commit author with GitHub usernames. Internally postprocessors and preprocessors are the same. See commit_preprocessors for more detail and examples, it uses the same syntax.

output​

Output file path for the changelog. You can also use the --output argument to override this value.