Skip to main content

What's new in 1.2.0?

· 6 min read
Orhun Parmaksız
Orhun Parmaksız
Author of 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:

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:

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

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.

New GitHub Action​

A new GitHub Action for git-cliff has been created by @jackton1!

tj-actions/git-cliff is another GitHub Action that you can use to generate changelogs for your project.

It uses a generic cliff-template.toml without the need to maintain multiple configuration files for each project or you can optionally provide a customized template as a path or URL which falls back to project's cliff.toml if it exist.

- name: Check out repository
  uses: actions/checkout@v3
  with:
    fetch-depth: 0

- name: Run git-cliff
  uses: tj-actions/git-cliff@v1

See the documentation for more information.

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:

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!

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