What's new in 2.10.0?

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

What's new? ⛰️​

The full changelog can be found here.

📈 Release statistics​

git-cliff now supports adding various release-related metrics to the changelog via statistics variable!

You can use it in your template as follows:

[changelog]
body = """
### Commit Statistics

- {{ statistics.commit_count }} commit(s) contributed to the release.
- {{ statistics.commits_timespan | default(value=0) }} day(s) passed between the first and last commit.
- {{ statistics.conventional_commit_count }} commit(s) parsed as conventional.
- {{ statistics.links | length }} linked issue(s) detected in commits.

{%- for link in statistics.links %}
      {{ "  " }}- [{{ link.text }}]({{ link.href }}) (referenced {{ link.count }} time(s))
{%- endfor %}

- {{ statistics.days_passed_since_last_release }} day(s) passed between releases.

"""

This will render a section like this in the changelog:

## Commit Statistics

- 5 commit(s) contributed to the release.
- 0 day(s) passed between the first and last commit.
- 5 commit(s) parsed as conventional.
- 3 linked issue(s) detected in commits.
  - [#452](https://github.com/orhun/git-cliff/issues/452) (referenced 2 time(s))
  - [#1148](https://github.com/orhun/git-cliff/issues/1148) (referenced 1 time(s))
  - [ietf-rfc3986](https://datatracker.ietf.org/doc/html/rfc3986) (referenced 1 time(s))
- 1430 day(s) passed between releases.

See release statistics for the available variables and more details.

Thanks to Shingo OKAWA for the implementation in #1151!

📝 New template​

Related to the new statistics feature, we added a new built-in template called statistics.toml!

It can be used as follows:

$ git cliff --config statistics

To initialize cliff.toml with it:

$ git cliff --init statistics

 INFO  git_cliff > Saving the configuration file (statistics) to "cliff.toml"

It serves the purpose of providing a basic template that includes release statistics. You can use it as a starting point for your own changelog template or simply use it as is.

📁 Include/exclude paths in config​

As highly requested, you can now include or exclude specific paths in your changelog generation via the include_paths and exclude_paths options in the configuration file.

[git]
include_paths = ["src/", "doc/**/*.md"]
exclude_paths = ["unrelated/"]

These options are the same as providing --include-paths and --exclude-paths command line arguments.

Thanks to @Kriskras99 for implementing this in #1173!

🧮 Support matching arrays via parsers​

The commit parser has been extended to support regex matching on array values, such as remote.pr_labels.

For example, this makes it possible to group commits based on their GitHub labels as follows:

[git]
commit_parsers = [
  { field = "remote.pr_labels", pattern = "duplicate|invalid|wontfix|skip changelog", skip = true },
  { field = "remote.pr_labels", pattern = "breaking change", group = "<!-- 0 -->🏗️ Breaking Changes" },
  { field = "remote.pr_labels", pattern = "feature|deprecation", group = "<!-- 1 -->🚀 Features" },
  { field = "remote.pr_labels", pattern = "enhancement|refactor", group = "<!-- 1 -->🛠️ Enhancements" },
  { field = "remote.pr_labels", pattern = "bug|regression", group = "<!-- 2 -->🐛 Bug Fixes" },
  { field = "remote.pr_labels", pattern = "security", group = "<!-- 3 -->🔐 Security" },
  { field = "remote.pr_labels", pattern = "documentation", group = "<!-- 4 -->📝 Documentation" },
  { message = ".*", group = "<!-- 5 -->🌀 Miscellaneous" },
]

🗑️ Empty header/footer as default​

In the previous release, we internally started initializing the configuration file with default values. This sadly made it impossible to render a changelog without a header or footer.

This behavior has been reverted in this release and the default values for [changelog.header] and [changelog.footer] are now empty. Meaning that the following is a minimal configuration that will render a changelog without a header or footer:

[changelog]
body = """
{% if version %}\
    ## {{ version | trim_start_matches(pat="v") }} - {{ timestamp | date(format="%Y-%m-%d") }}\
{% else %}\
    ## Unreleased\
{% endif %}\
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}\
        - {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}
    {% endfor %}\
{% endfor %}\n
"""

🐧 Gentoo support​

git-cliff made its way into the Gentoo Linux package repository! 🎉

It can be installed via the following command:

emerge git-cliff

See the package page here.

Thanks to @aspann for packaging!

🏴 Spaces instead of tabs​

git-cliff now uses spaces instead of tabs throughout the codebase! This change made the code more consistent with the Rust community's conventions and improved readability.

🧰 Other​

• (config) Check if commit.footers is defined in detailed example (#1170) - (078545f)
• (generation) Ensure skip_tags condition is evaluated first (#1190) - (318be66)
• (repo) Use the correct order while diffing paths (#1188) - (ff6c310)
• (config) Implement FromStr instead of Config::parse_from_str() (#1185) - (692345e)
• (ci) Apply security best practices (#1180) - (a32deca)
• (fixture) Add test fixture for overriding the conventional scope (#1166) - (cb84a08)
• (build) Bump MSRV to 1.85.1 - (d8279d4)
• (crate) Remove Rust nightly requirement - (4f3e5af)

New Contributors ❤️​

• @Nick2bad4u made their first contribution in #1180
• @aspann made their first contribution in #1203
• @muzimuzhi made their first contribution in #1200
• @j-g00da made their first contribution in #1188
• @Kriskras99 made their first contribution in #1173
• @wetneb made their first contribution in #1165
• @gmeligio made their first contribution in #1170
• @LitoMore made their first contribution in #1164

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 Twitter & Mastodon to not miss any news!

Support 🌟​

If you liked git-cliff and/or my other projects on GitHub, consider donating to support my open source endeavors.

• 💖 GitHub Sponsors: @orhun
• ☕ Buy Me A Coffee: https://www.buymeacoffee.com/orhun

Have a fantastic day! ⛰️