What's new in 1.2.0? - Git Cliff

In this post, I'm giving a brief introduction to the new features in the 1.2.0 release while giving insight into the future 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.

Today, the new version of git-cliff (1.2.0) is released. There are a couple of major cool features that I believe are interesting and also there were some internal library changes. Let's have a look!

What's new?

The full changelog can be found here.

Improved documentation

git-cliff documentation is moved to https://git-cliff.org.

It is surely better than cluttering up the README.md with all the information.

The source for the website can be found here.

Python Integration

For Python projects, you can now place the git-cliff configuration inside pyproject.toml as follows:

toml

name = "..."

[project]
dependencies = []

[tool.git-cliff.changelog]
header = "All notable changes to this project will be documented in this file."
body = "..."
footer = "<!-- generated by git-cliff -->"
# see [changelog] section for more keys

[tool.git-cliff.git]
conventional_commits = true
commit_parsers = []
filter_commits = false
# see [git] section for more keys

See the documentation for more information.

Thanks to @radusuciu for the implementation!

Better commit grouping

You can now use regex values while grouping the commits via commit_parsers.

Let's say we have this commit history for example:

* fix(args): rename help argument due to conflict
* feat(parser): add ability to parse arrays

For this configuration:

toml

# regex for parsing and grouping commits
commit_parsers = [
    { message = '^fix\((.*)\)', group = 'Fix (${1})' },
    { message = '^feat\((.*)\)', group = 'Feat (${1})' },
]

We get:

## [1.0.0] - 2021-07-18

### Feat (parser)

- Add ability to parse arrays

### Fix (args)

- Rename help argument due to conflict

Thanks to @erwinc1 for reporting the issue!

Overriding configuration with environment variables

It was reported by @mackness on Discord that overriding the nested configuration values with environment variables was not working as expected. So we made some changes:

The prefix for environment variables is changed to GIT_CLIFF (from CLIFF).
"__" can be used as the separator for nested fields.

For example:

GIT_CLIFF__CHANGELOG__FOOTER overrides changelog.footer
GIT_CLIFF__GIT__IGNORE_TAGS overrides git.ignore_tags

See the documentation for more information.

Thanks to @mackness for the implementation!

New configuration file

For my own projects such as halp and linuxwave, I started to use a fancier git-cliff configuration so I thought it would be nice to use it for the git-cliff repository as well.

Just to avoid confusion: the default (basic) template has not changed. I'm just maintaining another cliff.toml at the root of the repository now.

cliff.toml (default)
cliff.toml (new)

The changelog looks something like this now:

## [unreleased]

### ⛰️ Features

- _(cache)_ Use cache while fetching pages
- _(config)_ Support multiple file formats

## [1.0.1] - 2021-07-18

### 🚜 Refactor

- _(parser)_ Expose string functions

### ⚙️ Miscellaneous Tasks

- _(release)_ Add release script

See the other template examples in the documentation.

Internal changes

Here is a list of changes that are worth mentioning if you use git-cliff/git-cliff-core in your Rust project as a library:

Move changelog module to git-cliff-core (2ab2c8f)
- This reduces the number of dependencies since you will only depend on git-cliff-core for changelog generation.
Make the fields of Signature public (104aac9)
- Useful if you want to construct this struct manually.

Console interview

The Console newsletter interview came out where I talk about the story behind git-cliff, my motivation, and the technical challenges that I faced during development.

Read: Console #141 - The Open Source Newsletter

Discord server

If you are having a problem with git-cliff or want to contribute to the project or you just want to chit-chat, feel free to join our Discord server!

Looking forward

Upcoming features

Here is the list of open pull requests that I'm planning to focus on for the next releases:

Publish git-cliff on PyPI
- This would make it seamless for Python projects to install and use git-cliff and would pair nicely with the newly added support for configuration in pyproject.toml. It also fits nicely in the recent rustification of python tooling trend.
Add postprocessors to changelog
- This will enable things like replacing usernames with GitHub usernames for the generated changelog.

Also, see the project issues.

Apart from those, I'm planning really big updates for the future that will revolutionize the changelog generation. Stay tuned! 🚀

New organization

I created an organization on GitHub: https://github.com/git-cliff

The following repositories will be moved there:

orhun/git-cliff -> git-cliff/git-cliff
orhun/git-cliff-action -> git-cliff/action

Just a heads-up :3

If you have a git-cliff-related repository that you're possibly interested in maintaining as a part of this organization, hit me up!

Contributions

Any contribution is highly appreciated! There are contribution guidelines for getting started.

Feel free to submit issues and throw in ideas!

Donate

If you liked git-cliff and/or my other projects on GitHub, consider donating to support my open source endeavors.

💖 https://donate.orhun.dev

Have a wonderful day! ⛰️