git-cliff is a command-line tool that provides a highly customizable way to generate changelogs from the Git history.

If you pass multiple values to --include-path, --exclude-path, --with-commit, or --skip-commit: you need to repeat the option for each value:

• git cliff --include-path "src/" "docs/"

• git cliff --include-path "src/" --include-path "docs/"

For Rust API users 🦀

Opt::config is now an Option<PathBuf>. The public changelog and remote context types also gained fields, so code constructing them with struct literals must initialize the new fields.

git-cliff-core now uses git2 0.21. If you use git2 types exposed by its public API, update your git2 dependency as well.

For packagers 📦

Building git-cliff from source now requires Rust 1.88.0 or newer.

The upgrade to git2 0.21 includes a libgit2 SONAME change. Dynamically linked packages must be rebuilt against the new libgit2 version.

💻 CLI​

Smarter config discovery: when --config is omitted, git-cliff automatically looks for a configuration file. (#1584)

Custom templates: you can now keep your own configuration templates in a directory and initialize them by name with --init.

Use --templates-dir (or GIT_CLIFF_TEMPLATES_DIR) to set the directory and --list-templates to see all built-in and custom templates. (#1583)

$ tree ~/my-templates ~/my-templates ├── company.toml └── minimal.toml

$ git cliff --templates-dir ~/my-templates --init company

$ git cliff --list-templates --templates-dir ~/my-templates azure-devops-keepachangelog cocogitto company ...

Templates from files: you can now place your changelog body template in a file and load it with --body-file, making multiline templates easier to manage than passing them directly with --body. (#1574)

$ git cliff --body-file changelog-body.tera

Safer multi-value arguments: path and commit options now consume one value per occurrence, preventing a trailing positional range from being mistaken for another option value. (#1614)

Repeat the option for each path

$ git cliff --include-path "src/" --include-path "docs/" v1.0.0..v2.0.0

Or pass path patterns as one quoted, space-delimited value

$ git cliff --include-path "src/** docs/**" v1.0.0..v2.0.0

The positional range can also come first

$ git cliff v1.0.0..v2.0.0 --include-path "src/" --include-path "docs/"

🧩 Templating​

git-cliff can now format markdown! (#1610)

It is opt-in and can be enabled via the format option:

[changelog] format = true

info

Formatting normalizes headings, list markers and excessive blank lines. It supports GitHub-flavored Markdown features such as tables, strikethrough, task lists and footnotes and only runs for stdout, extension-less paths and .md output.

Ambiguous bare brackets such as [unreleased] are escaped according to CommonMark rules.

New filters: two new filters give you more control over how releases and commits are grouped:

commit_groups preserves first appearance order or follows the order of commit_parsers_groups. (#1518)

tip

If you were using numbered HTML comments to control the group order, you can now remove them:

commit_parsers = [

• { message = "^feat", group = "<!-- 0 -->Features" },
• { message = "^fix", group = "<!-- 1 -->Bug Fixes" },

• { message = "^feat", group = "Features" },
• { message = "^fix", group = "Bug Fixes" }, ]

Then replace the group_by loop with commit_groups(groups=commit_parsers_groups):

-{% for group, commits in commits | group_by(attribute="group") %}

• {{ group | striptags | trim | upper_first }}

• {% for commit in commits %}- {{ commit.message }} +{% for entry in commits | commit_groups(groups=commit_parsers_groups) %}

• {{ entry.group | trim | upper_first }}

• {% for commit in entry.commits %}- {{ commit.message }} {% endfor %} {% endfor %}

Each returned entry contains the group name in entry.group and its commits in entry.commits.

group_by_scope groups releases at a chosen semantic-version scope such as major, minor, or patch, with support for version prefixes. (#1547)

{% for version, releases in releases | group_by_scope(scope="minor", prefix="v") %}

{{ version }}

{% for release in releases %}

• {{ release.version }} {% endfor %} {% endfor %}

Releases v0.1.0, v0.1.1 and v0.2.0 render as:

v0.1

• v0.1.1
• v0.1.0

v0.2

• v0.2.0

New variables: remote metadata now exposes more information for changelog templates:

commit.remote.pr_author contains the author of the matched pull request. (#1613)

{ "commits": [ { "remote": { "username": "merge-maintainer", "pr_author": "pull-request-author", "pr_number": 42 } } ] }

info

pr_author is more reliable than resolving the commit author's email for squash merges, where username can point to the maintainer who merged the change.

[github|gitlab|etc].contributors[].pr_numbers contains every pull request attributed to a contributor in the release, sorted by number. The existing pr_number field remains available for compatibility. (#1546)

{ "github": { "contributors": [ { "username": "contributor", "pr_number": 42, "pr_numbers": [42, 57, 81] } ] } }

Built-in GitLab templates: (#1561)

gitlab generates concise release notes with merge request, contributor and tag links:

$ git cliff --config gitlab

gitlab-keepachangelog generates a more detailed Keep a Changelog layout with GitLab commit and merge request links:

$ git cliff --config gitlab-keepachangelog

You can also use either preset as the starting point for your own configuration:

$ git cliff --init gitlab-keepachangelog

⚙️ Configuration​

Skip version bumps for selected commits: different commit types can now be excluded from version bump calculations with no_increment_regex. (#1522)

[bump] no_increment_regex = "chore|ci|docs"

Configure remote request timeouts: remote metadata requests now have a configurable http_timeout. (#1580)

[remote.github] http_timeout = "60s"

Better prepend support: the new header_marker tells git-cliff where the header ends, so it can remove the old header before writing the new one. (#1603)

[changelog] header = """

Changelog

Tracked releases: {{ releases | length }} """ header_marker = "<!-- git-cliff: end of header -->"

Then prepend a new release as usual:

$ git cliff --unreleased --prepend CHANGELOG.md

The marker is written automatically after the rendered header:

Changelog

Tracked releases: 1

<!-- git-cliff: end of header -->

Unreleased

On the next --prepend, git-cliff removes everything through the marker before writing the updated header.

Configuration schema: the git-cliff configuration schema is now available on SchemaStore, enabling validation and autocompletion in supported editors. (#1577)

tip

To select it explicitly in a Taplo-compatible editor, add this directive at the top of your configuration:

#:schema https://www.schemastore.org/git-cliff.json

🌳 Git​

Correct releases across merged branches: commits are now assigned to releases using Git graph reachability. (#1601)

Why this is big?

Consider a feature branch that splits before v1.0.0 but is merged afterward:

F---G /
A---B---C---D---M main | v1.0.0

F and G are not part of v1.0.0. However, a flattened git log can interleave commits from both branches and make them look like they belong to that release.

git-cliff now checks the actual commit graph instead. In this example, F and G stay under Unreleased until they are included in a later tag.

This fixes changelogs that list changes under a release that never shipped them, omit those changes from Unreleased or disagree with the actual previous_tag..tag history. It is especially useful for repositories with long-lived release branches, backports or branches that are merged after a release.

$ git cliff --limit-tags 10

You can also set limit_tags in your configuration:

[git] limit_tags = 10

Nested annotated tags: tags that point to other annotated tags are peeled all the way to their commit and are no longer silently omitted. (#1360)

Respect commits listed in .git-blame-ignore-revs: they are now automatically excluded from the changelog. (#1585)

Mass formatting

67b8f240063d0d5b8f6c58be198d31e36fbf251a

⚡ Performance​

Commit statistics are no longer calculated unless a template, parser, or --context output actually needs them. This avoids walking every diff for changelogs that do not use statistics, significantly reducing unnecessary work on larger repositories. (#1543)

Any contribution is highly appreciated! See the contribution guidelines for getting started.

Feel free to submit issues and join our Discord / Matrix for discussion!

Follow git-cliff on X & Mastodon to not miss any news!