Skip to main content

What's new in 2.0.0?

Β· 7 min read
Orhun ParmaksΔ±z
Author of git-cliff

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 -->
tip

For detailed documentation and usage examples, check out the GitHub integration!

warning

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:


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 run git cliff --bump, you will see testing/v1.0.0-beta.2 in your changelog.
  • If no tags exist, --bump will yield 0.1.0 as default.
  • Other behavioral fixes!

πŸ“š Documentation Improvements​

brew install git-cliff

🌐 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.

Have a fantastic day! ⛰️