What's new in 2.4.0?

June 26, 2024 · 6 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.

🍵 Gitea Integration

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:

Usernames (${{ commit.gitea.username }} or ${{ contributor.username }})
Contributors list (${{ gitea.contributors }})
Pull requests (${{ 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:

Check out the quickstart guide for installation / initialization.
Set up the Git remote for your GitLab project.
Update the changelog configuration to use the template variables.

tip

See the Gitea integration for detailed documentation and usage examples. It works very similar to the GitHub integration.

📤 Bump based on pattern

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

⬆️ Set initial tag for bump

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` argument

The 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"

📝 Header template

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

^{There is a pending issue that needs fixing for --prepend to work with header template.}

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 },
]

📩 Support tag messages

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"

📂 Repository path in context

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)

📡 Remote data in context

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
        },
    ],
}

🧰 Other

(website) Add information about --bump with tag prefixes (#695) - (4cd18c2)
(fixture) Support running fixtures on mingw64 (#708) - (dabe716)

Contributions 👥

@MeitarR made their first contribution in #713
@bukowa made their first contribution in #696
@Cyclonit made their first contribution in #698
@jan-ferdinand made their first contribution in #569
@Theta-Dev made their first contribution in #680
@tcarmet made their first contribution in #694

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? ⛰️​

🍵 Gitea Integration​

📤 Bump based on pattern​

⬆️ Set initial tag for bump​

⚙️ --ignore-tags argument​

📝 Header template​

🧮 Parse commits by footer​

📩 Support tag messages​

📂 Repository path in context​

📡 Remote data in context​

🧰 Other​

Contributions 👥​

Support 🌟​