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.
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.
๐งฐ 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! โฐ๏ธ