website/blog/git-cliff-2.0.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.
This highly requested feature is now experimentally available with the 2.0.0 version of git-cliff!
For repositories hosted on GitHub, you can now use the following variables in your changelog:
${{ commit.github.username }} or ${{ contributor.username }})${{ github.contributors }})${{ commit.github.pr_number }} or ${{ contributor.pr_number }})To quickly set things up for your project, you can use the built-in GitHub template:
# creates cliff.toml
$ git cliff --init github
And simply run git cliff to generate a changelog 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 -->
:::tip
For detailed documentation and usage examples, check out the GitHub integration!
:::
I gave a talk about git-cliff at RustLab 2023 - you can watch the recording here:
As briefly mentioned, the example templates are now embedded into the binary which means you can quickly initialize git-cliff or generate a changelog using one of them.
# creates cliff.toml with keepachangelog template
$ git cliff --init keepachangelog
# generates a changelog in keepachangelog format
$ git cliff --config keepachangelog
Here is the full list of supported templates as of now:
keepachangelog.toml: changelog in Keep a Changelog format.github.toml: changelog in the GitHub's format.github-keepachangelog.toml: combination of the previous two formats.detailed.toml: changelog that contains links to the commits.minimal.toml: minimal changelog.scoped.toml: changelog with commits are grouped by their scopes.scopesorted.toml: changelog with commits grouped by their scopes and sorted by group.cocogitto.toml: changelog similar to cocogitto's format.unconventional.toml: changelog for unconventional commits.Now you can use a template in [changelog.footer] as well!
Before:
# changelog footer
footer = """
<!-- generated by git-cliff -->
"""
After:
# template for the changelog footer
footer = """
<!-- generated by git-cliff at {{ now() | date(format="%Y-%m-%d") }} -->
"""
For example, keepachangelog.toml uses this for adding links to the end of the changelog.
# template for the changelog footer
footer = """
{% for release in releases -%}
{% if release.version -%}
{% if release.previous.version -%}
[{{ release.version | trim_start_matches(pat="v") }}]: \
https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
/compare/{{ release.previous.version }}..{{ release.version }}
{% endif -%}
{% else -%}
[unreleased]: https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}\
/compare/{{ release.previous.version }}..HEAD
{% endif -%}
{% endfor %}
<!-- generated by git-cliff -->
"""
Results in:
[unreleased]: https://github.com/orhun/git-cliff/compare/v1.4.0..HEAD
[1.4.0]: https://github.com/orhun/git-cliff/compare/v1.3.1..v1.4.0
[1.3.1]: https://github.com/orhun/git-cliff/compare/v1.3.1-rc.0..v1.3.1
[1.3.1-rc.0]: https://github.com/orhun/git-cliff/compare/v1.3.0..v1.3.1-rc.0
Do you want to skip erroneous commits in the changelog? We now support two comfortable ways of doing that.
.cliffignoreYou can now add a .cliffignore file at the root of your repository for listing the commits that will be skipped:
# skip commits by their SHA1
4f88dda8c746173ea59f920b7579b7f6c74bd6c8
10c3194381f2cc4f93eb97404369568882ed8677
--skip-commitYou can skip commits by using this argument as follows:
$ git cliff --skip-commit 10c3194381f2cc4f93eb97404369568882ed8677 \
--skip-commit 4f88dda8c746173ea59f920b7579b7f6c74bd6c8
If you want to use the --bump option but are only interested in the bumped version instead of the entire changelog, you can simply use the newly added --bumped-version flag!
# print the next semantic version
$ git cliff --bumped-version
v2.0.0
If you are using external commands (e.g. via replace_command) in your configuration, you can now entirely skip executing those commands with --no-exec flag.
$ git cliff --no-exec
For example, this is useful in the cases where the execution takes time.
The template context has a new field called merge_commit (bool) which can be used to filter out merge commits.
For example, you can use filter(attribute="merge_commit", value=false) as follows:
{% for group, commits in commits |
filter(attribute="merge_commit", value=false) |
group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | upper_first }}\
{% endfor %}
{% endfor %}\n
It is now possible to use the SHA1 of a commit with commit_parsers.
For example, to skip a specific commit:
commit_parsers = [
{ sha = "f6f2472bdf0bbb5f9fcaf2d72c1fa9f98f772bb2", skip = true }
]
To override the group of a specific commit:
commit_parsers = [
{ sha = "f6f2472bdf0bbb5f9fcaf2d72c1fa9f98f772bb2", group = "Stuff" }
]
It is now possible to use regex-replace for the scope value in commit_parsers:
[git]
# regex for parsing and grouping commits
commit_parsers = [
{ message = "^\\[(.*)\\]", group = "Changes to ${1}", scope = "${1}" },
]
In this example, [codebase]: rewrite everything in Rust will appear in the changelog as:
### Changes to codebase
- (codebase) Rewrite everything in Rust
There was some love towards --bump flag to improve its behavior:
testing/v1.0.0-beta.1 as the current version and if you run git cliff --bump, you will see testing/v1.0.0-beta.2 in your changelog.--bump will yield 0.1.0 as default.Added Tips And Tricks!
Added installation instructions for Homebrew
brew install git-cliff
There were a lot of bug fixes and improvements in this release but mainly:
CHANGELOG.md as default missing value for output option (#354)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! ⛰️