website/blog/git-cliff-2.10.0.md
git-cliff is a command-line tool that provides a highly customizable way to generate changelogs from the Git history.
The full changelog can be found here.
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!
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.
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!
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" },
]
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
"""
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!
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.
:::info[Fun Fact]
Hard tabs are used in around 0.1% of Rust projects. I don't know why I went with that config option when I first started this project. I guess I was a rebel back then.
:::
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!
If you liked git-cliff and/or my other projects on GitHub, consider donating to support my open source endeavors.
Have a fantastic day! ⛰️