About

git-cliff can generate changelog files from the Git history by utilizing conventional commits as well as regex-powered custom parsers. The changelog template can be customized with a configuration file to match the desired format.

Table of Contents

• About
• Installation
  • From crates.io
  • Binary Releases
• Usage
  • Command Line Arguments
• Configuration File
  • changelog
    • header
    • body
    • trim
    • footer
  • git
    • conventional_commits
    • commit_parsers
    • filter_commits
    • tag_pattern
    • skip_tags
• Templating
  • Context
    • Conventional Commits
    • Non-Conventional Commits
  • Syntax
• Examples
  • Simple
  • Other
• Docker
• GitHub Action
• Similar Projects
• License
• Copyright

Installation

From crates.io

git-cliff can be installed from crates.io:

cargo install git-cliff

Binary Releases

See the available binaries for different operating systems/architectures from the releases page.

Usage

Command Line Arguments

git-cliff [FLAGS] [OPTIONS] [RANGE]

Flags:

-v, --verbose       Increases the logging verbosity
-l, --latest        Processes the commits starting from the latest tag
-u, --unreleased    Processes the commits that do not belong to a tag
-h, --help          Prints help information
-V, --version       Prints version information

Options:

-c, --config <PATH>        Sets the configuration file [env: CONFIG=]  [default: cliff.toml]
-w, --workdir <PATH>       Sets the working directory [env: WORKDIR=]
-r, --repository <PATH>    Sets the repository to parse commits from [env: REPOSITORY=]
-p, --changelog <PATH>     Prepends entries to the given changelog file [env: CHANGELOG=]
-o, --output <PATH>        Writes output to the given file [env: OUTPUT=]
-t, --tag <TAG>            Sets the tag for the latest version [env: TAG=]
-b, --body <TEMPLATE>      Sets the template for the changelog body [env: TEMPLATE=]
-s, --strip <PART>         Strips the given parts from the changelog [possible values: header, footer, all]

Args:

<RANGE>    Sets the commit range to process

Configuration File

git-cliff configuration file supports TOML (preferred) and YAML formats.

See cliff.toml for an example.

changelog

This section contains the configuration options for changelog generation.

[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 for more detail.

trim

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

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

footer

Footer text that will be added to the end of the changelog.

git

This section contains the parsing and git related configuration options.

[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.

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".

filter_commits

If set to true, commits that are not matched by 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:

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 format is used in the following examples for the representation of a context.

Conventional Commits

conventional_commits = true

For a conventional commit like this,

<type>[scope]: <description>

[body]

[footer(s)]

following context is generated to use for templating:

{
  "version": "v0.1.0-rc.21",
  "commits": [
    {
      "id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
      "group": "<type> (overrided by commit_parsers)",
      "scope": "[scope]",
      "message": "<description>",
      "body": "[body]",
      "footers": ["[footer]", "[footer]"],
      "breaking": false
    }
  ],
  "commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210 (release commit)",
  "timestamp": 1625169301,
  "previous": {
    "version": "previous release"
  }
}

Non-Conventional Commits

conventional_commits = false

If conventional_commits is set to false, then some of the fields are omitted from the context or squashed into the message field:

{
  "version": "v0.1.0-rc.21",
  "commits": [
    {
      "id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
      "group": "(overrided by commit_parsers)",
      "message": "(whole commit message including description, footers, etc.)"
    }
  ],
  "commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210 (release commit)",
  "timestamp": 1625169301,
  "previous": {
    "version": "previous release"
  }
}

Syntax

git-cliff uses Tera as a template engine which has a syntax based on Jinja2 and Django templates.

There are 3 kinds of delimiters and those cannot be changed:

• {{ and }} for expressions
• {% or {%- and %} or -%} for statements
• {# and #} for comments

See the Tera Documentation for more information about control structures, built-ins filters, etc.

Custom built-in filters that git-cliff uses:

• upper_first: Converts the first character of a string to uppercase.

Examples

Examples are based on the following Git history:

* df6aef4 (HEAD -> master) feat(cache): use cache while fetching pages
* a9d4050 feat(config): support multiple file formats
* 06412ac (tag: v1.0.0) chore(release): add release script
* e4fd3cf refactor(parser): expose string functions
* ad27b43 docs(example)!: add tested usage example
* 9add0d4 fix(args): rename help argument due to conflict
* a140cef feat(parser): add ability to parse arrays
* 81fbc63 docs(project): add README.md
* a78bc36 Initial commit

Simple Changelog

TODO

Detailed Changelog

TODO

Prepending Entries

TODO

Other

• Setting the release notes for GitHub releases using git-cliff-action
• Setting 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 present) is to use the available tags from Docker Hub:

docker run -t -v "$(pwd)":/app/ orhunp/git-cliff:latest

Or you can use the image from the GitHub Package Registry:

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 via git-cliff-action.

- name: Generate a changelog
  uses: orhun/git-cliff-action@v1
  with:
    config: cliff.toml
    args: --verbose
  env:
    OUTPUT: CHANGELOG.md

See the repository for other examples.

Similar Projects

• git-journal - The Git Commit Message and Changelog Generation Framework
• clog-cli - Generate beautiful changelogs from your Git commit history
• relnotes - A tool to automatically generate release notes for your project.
• cocogitto - A set of CLI tools for the conventional commit and semver specifications.

License

GNU General Public License (v3.0)

Copyright

Copyright © 2021, git-cliff contributors