What's new in 2.0.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.
π GitHub Integrationβ
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:
- GitHub usernames (
${{ commit.github.username }}
or${{ contributor.username }}
) - Contributors list (
${{ github.contributors }}
) - Pull requests (
${{ 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 -->
For detailed documentation and usage examples, check out the GitHub integration!
This is an experimental feature so please report bugs to help us improve!
π¦ RustLab 2023β
I gave a talk about git-cliff
at RustLab 2023 - you can watch the recording here:
π Built-in Templatesβ
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.
π Footer Templateβ
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
π§Ά Improve Skippingβ
Do you want to skip erroneous commits in the changelog? We now support two comfortable ways of doing that.
1. .cliffignore
β
You 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
2. --skip-commit
β
You can skip commits by using this argument as follows:
$ git cliff --skip-commit 10c3194381f2cc4f93eb97404369568882ed8677 \
--skip-commit 4f88dda8c746173ea59f920b7579b7f6c74bd6c8
π¨οΈ Print Bumped Versionβ
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
π« Disable Command Executionβ
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.
π Filter Merge Commitsβ
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
π Match by commit SHAβ
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" }
]
π Regex Scope Valuesβ
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
π Bump Improvementsβ
There was some love towards --bump
flag to improve its behavior:
- Tag prefixes are now supported!
- This means that for example if you have
testing/v1.0.0-beta.1
as the current version and if you rungit cliff --bump
, you will seetesting/v1.0.0-beta.2
in your changelog.
- This means that for example if you have
- If no tags exist,
--bump
will yield0.1.0
as default. - Other behavioral fixes!
π Documentation Improvementsβ
-
Added Tips And Tricks!
-
Added installation instructions for Homebrew
brew install git-cliff
- Added instructions for adding new test fixtures
π Website Improvementsβ
- Made dark theme default (sorry moths)
- Added a search bar
π§° Otherβ
There were a lot of bug fixes and improvements in this release but mainly:
- (changelog) Fix previous version links (#364)
- (cli) Fix broken pipe when stdout is interrupted (#407)
- (commit) Trim the trailing newline from message (#403)
- (git) Sort commits in topological order (#415)
- (args) Set
CHANGELOG.md
as default missing value for output option (#354) - (changelog) Disable the default behavior of next-version (#343)
Contributions π₯β
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! β°οΈ