What's new in 2.4.0? ๐
git-cliff is a command-line tool (written in Rust) that provides a highly customizable way to generate changelogs from git history.
It supports using custom regular expressions to alter changelogs which are mostly based on conventional commits. With a single configuration file, a wide variety of formats can be applied for a changelog, thanks to the Jinja2/Django-inspired template engine.
More information and examples can be found in the GitHub repository.
What's new? โฐ๏ธโ
The full changelog can be found here.
๐ต Gitea Integrationโ
git-cliff now supports integrating with repositories hosted on Gitea (e.g. Codeberg or your own instance!)
This means that you can now use the following variables in your changelog:
- Usernames (
${{ commit.gitea.username }}or${{ contributor.username }}) - Contributors list (
${{ gitea.contributors }}) - Pull requests (
${{ commit.gitea.pr_number }}or${{ contributor.pr_number }})
This means you can generate changelog entries like the following:
## What's Changed
- feat(commit): add merge_commit flag to the context by @orhun in #389
- test(fixture): add test fixture for bumping version by @orhun in #360
## New Contributors
- @someone made their first contribution in #360
- @cliffjumper made their first contribution in #389
<!-- generated by git-cliff -->
To set up git-cliff for your project, simply:
- Check out the quickstart guide for installation / initialization.
- Set up the Git remote for your GitLab project.
- Update the changelog configuration to use the template variables.
See the Gitea integration for detailed documentation and usage examples. It works very similar to the GitHub integration.
๐ค Bump based on patternโ
The --bump argument works as follows:
- "fix:" -> increments
PATCH- "feat:" -> increments
MINOR- "scope!" (breaking changes) -> increments
MAJOR
But what happens let's say you want to bump the major if the commit starts with "abc" instead?
Good news, git-cliff now supports bumping based on configurable custom patterns! Simply configure the following values in your configuration:
[bump]
custom_major_increment_regex = "abc"
custom_minor_increment_regex = "minor|more"
So with this commit history:
(HEAD -> main) abc: 1
(tag: 0.1.0) initial commit
The major will be bumped due to "abc" (0.1.0 -> 1.0.0)
$ git-cliff --bumped-version
1.0.0
โฌ๏ธ Set initial tag for bumpโ
When using --bump, if there are no initial tags are found then the default used to be hardcoded as 0.1.0.
Now you can configure this value in the configuration file as follows:
[bump]
initial_tag = "1.0.0"
You can also override this value from the command line as follows:
$ git-cliff --bump --tag=1.0.0
โ๏ธ --ignore-tags argumentโ
The value of [git.ignore_tags] can now be overridden by the newly added --ignore-tags argument:
$ git-cliff --ignore-tags "rc|v2.1.0|v2.1.1"
is the equivalent of:
[git]
# regex for ignoring tags
ignore_tags = "rc|v2.1.0|v2.1.1"
๐ Header templateโ
[changelog.header] is now a template similar to body and footer. It used to be a raw string value that is added to the top of the changelog but now you can use the template variables and functions in it!
For example:
[changelog]
# template for the changelog footer
header = """
# Changelog
{% for release in releases %}\
{% if release.version %}\
{% if release.previous.version %}\
<!--{{ release.previous.version }}..{{ release.version }}-->
{% endif %}\
{% else %}\
<!--{{ release.previous.version }}..HEAD-->
{% endif %}\
{% endfor %}\
"""
Will result in:
# Changelog
<!--v3.0.0..HEAD-->
<!--v0.2.0..v3.0.0-->
<!--v0.1.0..v0.2.0-->
--prepend to work with header template.
๐งฎ Parse commits by footerโ
You can now parse the commits by their footer value!
Let's say you want to skip this commit:
git commit -m "test: add more tests" -m "changelog: ignore"
This is now possible:
[git]
# regex for parsing and grouping commits
commit_parsers = [
{ footer = "^changelog: ?ignore", skip = true },
]
๐ฉ Support tag messagesโ
You can now include the tag messages (of release tags) in your changelog!
This can be useful for having "headlines" for a release like so:
## [1.0.1] - 2021-07-18
This is the release-tag message
The message is available in the context of the template as the {{ message }} variable:
{% if message %}
{{ message }}
{% endif %}\
You can also override the tag message for the unreleased changes via --with-tag-message argument as follows:
$ git cliff --bump --unreleased --with-tag-message "This is the release-tag message"
The recommended way of setting tag messages is to use annotated tags in your project:
$ git tag v1.0.0 -m "This is the release-tag message"
๐ Repository path in contextโ
You can now use {{ repository }} variable in the template to get the repository path:
## Release [{{ version }}] - {{ timestamp | date(format="%Y-%m-%d") }} - {{ repository }}
This is especially useful when you use git-cliff with multiple repositories. (e.g. git-cliff -r repo1 -r repo2)
๐ก Remote data in contextโ
We updated the changelog processing order to make remote data (e.g. GitHub commits, pull requests, etc.) available in the context.
For example:
$ git cliff --github-repo orhun/git-cliff -c examples/github.toml --no-exec -u -x
This command will now contain the GitHub data such as:
"github": {
"contributors": [
{
"username": "bukowa",
"pr_title": "style(lint): fix formatting",
"pr_number": 702,
"pr_labels": [],
"is_first_time": true
},
],
}
๐งฐ Otherโ
- (website) Add information about
--bumpwithtag prefixes(#695) - (4cd18c2) - (fixture) Support running fixtures on mingw64 (#708) - (dabe716)
Contributions ๐ฅโ
- @MeitarR made their first contribution in #713
- @bukowa made their first contribution in #696
- @Cyclonit made their first contribution in #698
- @jan-ferdinand made their first contribution in #569
- @Theta-Dev made their first contribution in #680
- @tcarmet made their first contribution in #694
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! โฐ๏ธ
