What's new in 2.0.0?

February 19, 2024 · 7 min read

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:

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

🧶 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

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! ⛰️

What's new? ⛰️​

🚀 GitHub Integration​

🦀 RustLab 2023​

📋 Built-in Templates​

📄 Footer Template​

🧶 Improve Skipping​

1. .cliffignore​

2. --skip-commit​

🖨️ Print Bumped Version​

🚫 Disable Command Execution​

🔄 Filter Merge Commits​

🔍 Match by commit SHA​

🔠 Regex Scope Values​

📈 Bump Improvements​

📚 Documentation Improvements​

🌐 Website Improvements​

🧰 Other​

Contributions 👥​

Support 🌟​