Why git-cliff for changelog generation

develop
git
Automatically generating a changelog can save a lot of administrative time, especially for a small group like ours. This post explains our reasons for using git-cliff to auto-generate changelogs.
Published

May 22, 2026

Context and problem statement

We originally used Commitizen for changelog generation, but we encountered some issues and limitations to it as our needs grew. So this post is explaining why we switched to git-cliff. See our previous post on using Commitizen for changelog generation for more information about the context and problem statement as well as the original reasons for using Commitizen.

This post explains some of our issues with Commitizen and why we switched to git-cliff.

Decision drivers

Commitizen worked fairly well for our needs for a while, but as we incorporated it in other, non-Python projects, we quickly started encountering some issues and limitations. Some of the issues we encountered include:

  • The changelog generated by Commitizen is not as easy to customise, but we need to be able to customise the changelog for different projects, like the Python packages, R packages, and documentation projects. For example, the website generator pkgdown for R packages expects a specific format for the NEWS.md file, but we couldn’t (easily) modify the changelog template to meet these requirements. Documentation projects include a lot more changes outside of refactor, fix, and feat, and therefore some relevant changes to those repos would often be missing from the changelog.
  • When generating the changelog to be included in the GitHub release notes, it would often add a commit message at the end of the changelog. It wasn’t clear how to remove it or even where it came from, as the CLI didn’t produce the same output.
  • We wanted something built in a more “formal” programming language, especially with the increase in supply chain attacks on e.g. Node.js packages. This isn’t a critical need for us, but it does need to support diverse project types, not just e.g. Python projects.

Considered options

There are numerous tools available for automatically generating changelogs for Git repositories following the Conventional Commit specification, as seen by this list by Conventional Commits. We considered the following options:

These were the only two that fit our needs for customisation and security that is still actively maintained. Most of the other options hadn’t been updated in years.

Cocogitto

Cocogitto is primarily focused on bumping versions and helping to release them, checking commits match Conventional Commits style, and for creating Conventional Commits. However, it does have a changelog generation feature.

Benefits

  • Is very well developed and documented.
  • Can create custom changelogs using the tera templating engine.
  • Written in Rust, which is a powerful, statically-typed language that is known for its performance and safety.

Drawbacks

  • Not as easily customisable as git-cliff (see below).

git-cliff

git-cliff is a changelog generator that can generate changelogs for Git repositories that follow the Conventional Commits specification. It can be customised to generate changelogs in different formats with different filters.

Benefits

  • Can generate changelogs based on commit messages following the SemVer and Conventional Commits specification.
  • Is very well documented.
  • Is actively maintained.
  • Can generate changelogs in different formats.
  • Allows for filtering and pre-processing of commits based on different criteria and patterns, which is really useful for us since we have different types of projects that require different processing needs.
  • Is written in Rust.
  • Produces consistent and predictable output, which means we can incorporate it easily into our workflow for generating GitHub release notes.
  • Can be easily installed and used through uv via uvx.

Drawbacks

  • Is primarily focused on changelog generation (e.g. can bump versions, but isn’t as easy to do), so we would have to use another tool for linting and version bumping.

Decision outcome

We have decided to use git-cliff because it is highly customisable, which means we can make it fit our needs for all our different projects.

Consequences

  • Because of our need to make custom changelogs for different projects, the maintenance cost will be higher than if we used something with defaults that were closer to what we needed. But unfortunately, there isn’t a tool that can meet all our needs without some customisation, so we have to accept this trade-off.
  • We introduce a new dependency, which brings with it some costs to security and maintenance. But git-cliff is actively maintained and written in Rust (which is known for its safety), so we accept this trade-off as well.
  • We will need to use another tool for linting and version bumping.

Resources used for this post