website/blog/git-cliff-2.4.0.md
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.
The full changelog can be found here.
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:
${{ commit.gitea.username }} or ${{ contributor.username }})${{ gitea.contributors }})${{ 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:
:::tip
See the Gitea integration for detailed documentation and usage examples. It works very similar to the GitHub integration.
:::
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
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 argumentThe 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"
[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-->
<sup> There is a pending issue that needs fixing for --prepend to work with header template. </sup>
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 },
]
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"
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)
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
},
],
}
--bump with tag prefixes (#695) - (4cd18c2)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! ⛰️