Skip to main content

What's new in 2.2.0? πŸ†•

Β· 4 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.

🎈 Configurable Bump Rules​

If you are a frequent user of --bump/--bumped-version flags then this new feature is for you!

git-cliff now supports customizing the behavior of version bumps.

Add the following section to your cliff.toml for configuration:

[bump]
# Configures automatic minor version increments for feature changes.
#
# When true, a feature will always trigger a minor version update.
#
# When false, a feature will trigger:
# - a patch version update if the major version is 0.
# - a minor version update otherwise.
features_always_bump_minor = true

# Configures 0 -> 1 major version increments for breaking changes.
#
# When true, a breaking change commit will always trigger a major version update
# (including the transition from version 0 to 1)
#
# When false, a breaking change commit will trigger:
# - a minor version update if the major version is 0.
# - a major version update otherwise.
breaking_always_bump_major = true

πŸ› οΈ Better Template Errors​

Template rendering errors are now more verbose!

For example, let's throw an error in the template with using throw function:

[changelog]
body = """
{{ throw(message="something happened!") }}
"""

When you run git-cliff:

 ERROR git_cliff > Template render error:
Function call 'throw' failed
something happened!

πŸ€– Auto Detecting Config​

If you configured git-cliff from Cargo.toml via metadata table ([workspace.metadata.git-cliff.changelog]), running git cliff is now simply enough!

$ git cliff

# is same as
$ git cliff --config Cargo.toml

We also updated the config detection mechanism to support the following cases:

cliff.tomlproject manifest (e.g. Cargo.toml)use config from:
βœ…βœ…cliff.toml
βœ…βŒcliff.toml
βŒβœ…Cargo.toml
❌❌builtin

See Rust & Python integration for more information.


🚦 Commit Processing Order​

The order of commit processing is changed from:

  1. Split commits
  2. Process commits

To:

  1. Process commits
  2. Split commits (and process the split commits)

This makes it possible to e.g. preprocess commits, split them by newline and then process each line as conventional commit.

See #555 for an example.


βœ‚οΈ Trim Text​

We changed the commit parser behavior to always trim the text (commit message, body, etc.) before matching it with a regex.

This means that you will be able to use $ in the regex for matching until the end.

For example:

[git]
commit_parsers = [
{ message = '^(fix|feat|setup|doc|refactor|test|optimization)\([A-Za-z0-9_-]+?\))+(:\ .*)$', group = "test"},
]

πŸš€ Quick Installation in CI​

You can now install git-cliff in your GitHub Actions CI easily with taiki-e/install-action!

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

- name: Install git-cliff
uses: taiki-e/install-action@git-cliff

- name: Generate changelog
run: git-cliff

🧰 Other​

  • (changelog) Return the last version if there is nothing to bump - (45c87f2)
  • (command) Add missing environment variables for Windows (#532) - (9722784)
  • (npm) Publish rc version for prereleases (#528) - (16bea51)
  • (pypi) Update maturin version (#539) - (10b7ab8)

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

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

What's new in 1.4.0?

Β· 4 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.

Bump version πŸ†™β€‹

git-cliff can calculate the next version based on conventional commits and bump the version for the unreleased changes for you!

--bump: Bumps the version for unreleased changes

For example, if you have 1.0.0 and committed "feat: xyz", git-cliff --bump --unreleased will create a changelog for 1.1.0.

How it works is that for a semantic versioning such as <MAJOR>.<MINOR>.<PATCH>:

  • "fix:" -> increments PATCH
  • "feat:" -> increments MINOR
  • "scope!" (breaking changes) -> increments MAJOR

Better grouping πŸ‘₯​

Now you can group commits by their attributes, i.e. name of the author, email, etc.

For example, to group the commits that belong to Dependabot under "Dependency Updates" in the changelog:

[git]
# regex for parsing and grouping commits
commit_parsers = [
{ field = "author.name", pattern = "dependabot\\[bot\\]", group = "Dependency Updates"},
]

This will result in:

### Dependency Updates

- _(deps)_ Bump regex from 1.9.6 to 1.10.0
- _(deps)_ Bump toml from 0.8.1 to 0.8.2
- _(deps)_ Bump regex from 1.9.5 to 1.9.6

The supported commit attributes (fields) are:

  • id
  • message
  • body
  • author.name
  • author.email
  • committer.email
  • committer.name

Glob -> Regex πŸ§Άβ€‹

[git].tag_pattern was only supporting glob patterns for matching (mostly due to the underlying support of such glob by git2), now it directly supports regular expressions:

[git]
- # glob pattern for matching git tags
+ # regex for matching git tags
- tag_pattern = "v[0-9]*"
+ tag_pattern = "v[0-9].*"

Auto-fix typos βœοΈβ€‹

Here is a git-cliff configuration for automatically fixing the typos in the commit messages before they appear in the changelog:

# regex for preprocessing the commit messages
commit_preprocessors = [
# Check spelling of the commit with https://github.com/crate-ci/typos
# If the spelling is incorrect, it will be automatically fixed.
{ pattern = '.*', replace_command = 'typos --write-changes -' },
]

This configuration was added to the git-cliff's repository config (not default) in #316 and runs typos for each commit. There is also a good first issue to improve this.

Emacs support πŸ˜ˆβ€‹

Check out git-cliff.el to generate, update and release changelog in Emacs.

RustLab 2023 πŸ“’β€‹

I'm happy to announce that I will be talking about git-cliff at RustLab 2023! πŸŽ‰

rustlab2023

https://rustlab.it/talks/turning-git-commits-into-changelog-with-git-cliff

In this talk, I will be sharing the story behind git-cliff, implementation details with certain design choices, and most importantly how to work with Git objects using Rust. Also, I will be sharing examples of how to use git-cliff and integrate it with your project.

Additionally, I will be giving tips on creating a successful command-line tool in Rust and publishing it as open source.

Contributions​

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

Feel free to submit issues and join Discord / Matrix!

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

What's new in 1.3.0?

Β· 4 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.

Fancier changelog πŸ¬β€‹

The changelog of git-cliff is looking more fancy now!

For example:

## [1.3.0-rc.1](https://github.com/orhun/git-cliff/compare/v1.2.0..v1.3.0-rc.1) - 2023-08-24

### ⛰️ Features

- _(changelog)_ [**breaking**] Add postprocessors ([#155](https://github.com/orhun/git-cliff/issues/155)) - ([5dc5fb7](https://github.com/orhun/git-cliff/commit/5dc5fb786db922322faacf928cc571a2d785cab2))

### πŸ› Bug Fixes

- _(cd)_ Do not publish release notes for pre-releases ([#249](https://github.com/orhun/git-cliff/issues/249)) - ([7a82aa1](https://github.com/orhun/git-cliff/commit/7a82aa1a769b2170ea7563d7df3c59da5a134201))
  • The title now has links to the compare changes page on GitHub
  • Each entry shows the issue/PR number and related commit
  • Emojis!

Configuration: https://github.com/orhun/git-cliff/blob/main/cliff.toml

Postprocessors βš™οΈβ€‹

Now you can post-process the changelog after generation:

An array of commit postprocessors for manipulating the changelog before outputting. Can e.g. be used for replacing commit author with GitHub usernames.

For example:

[changelog]
postprocessors = [{ pattern = "foo", replace = "bar"}]

A practical example is present in the default configuration:

[changelog]
# <REPO> will be replaced via postprocessors
body = """
## [{{ version }}](<REPO>/compare/{{ previous.version }}..{{ version }})
<!--trim-->
"""
# replace <REPO> with actual repository URL
postprocessors = [
{ pattern = '<REPO>', replace = "https://github.com/orhun/git-cliff" },
]

[git]
# replace issue numbers with <REPO>/issues/<num>
commit_preprocessors = [
{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](<REPO>/issues/${2}))" },
]

Imagine you created a tag (e.g. 0.2.0) with the following commit:

feat: add xyz (#1)

In the changelog, it will turn into:

## [0.2.0](https://github.com/orhun/git-cliff/compare/v0.1.0..v0.2.0)

### Features

- Add xyz ([#1](https://github.com/orhun/git-cliff/issues/1))

The way that it works is:

  1. The numbers in commit messages are replaced with <REPO>/issues/<num> with the help of git.preprocessors.
  2. The changelog is generated using changelog.body which has a couple of <REPO> usages.
  3. <REPO is replaced with the original repository URL in the final changelog using changelog.postprocessors.

PyPI Releases πŸβ€‹

git-cliff is now packaged for PyPI, the Python packaging index.

You can download it with pip:

pip install git-cliff

Optional git2 πŸ¦β€‹

If you are using git-cliff as a library, you can now get rid of git2 dependency by disabling the repo feature.

repo: Enable parsing commits from a git repository. Enabled by default. You can turn this off if you already have the commits to put in the changelog and you don't need git-cliff to parse them.

Here is an example from release-plz:

[dependencies]
git-cliff-core = { version = "1.3.0", default-features = false }

Cocogitto example πŸ“β€‹

cocogitto is one other great release tool and conventional commits toolbox written in Rust.

With the newly added cocogitto.toml example, you can generate changelogs similar to cocogitto's changelog format.

For example:

git cliff -c examples/cocogitto.toml

Results in:

# Changelog

All notable changes to this project will be documented in this file. See [conventional commits](https://www.conventionalcommits.org/) for commit guidelines.

---

## [unreleased]

### Bug Fixes

- **(cd)** do not publish release notes for pre-releases (#249) - ([7a82aa1](https://github.com/cocogitto/cocogitto/commit/7a82aa1a769b2170ea7563d7df3c59da5a134201)) - Orhun ParmaksΔ±z

Docker improvement πŸ‹β€‹

To avoid CVE-2022-24765 (safe directory vulnerability), we were copying the project files into the container. After #142 is merged, this is no longer the case and the Docker container can be run as follows:

- docker run -t -v "$(pwd)/.git":/app/ "orhunp/git-cliff:${TAG:-latest}"
+ docker run -t -v "$(pwd)":/app/ "orhunp/git-cliff:${TAG:-latest}"

RustLab 2023 πŸ“’β€‹

I'm happy to announce that I will be talking about git-cliff at RustLab 2023! πŸŽ‰

rustlab2023

https://rustlab.it/talks/turning-git-commits-into-changelog-with-git-cliff

In this talk, I will be sharing the story behind git-cliff, implementation details with certain design choices, and most importantly how to work with Git objects using Rust. Also, I will be sharing examples of how to use git-cliff and integrate it with your project.

Additionally, I will be giving tips on creating a successful command-line tool in Rust and publishing it as open source.

Contributions​

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

Feel free to submit issues and join Discord / Matrix!

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 an awesome day! ⛰️

What's new in 1.2.0?

Β· 6 min read
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! ⛰️

What's new in 0.5.0?

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

In this post, I'm explaining the new features in the 0.5.0 release while giving insight into the different use-cases.

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 I released the new version (0.5.0) of git-cliff. There are a couple of major features that I believe are interesting and they can potentially help with different use cases. Must be exciting, let's have a look!

What's new?​

--topo-order​

--topo-order : Sorts the tags topologically

Imagine you are working on parallel code lines and you have the following git history:

* 0000025 (tag: v0.1.1, fix_v1) fix: patch on v0.1.x
| * 0000050 (HEAD -> master) feat: fifth commit on master
| * 0000040 (tag: v0.2.0) feat: fourth commit on master
| * 0000030 chore: third commit on master
|/
* 0000020 (tag: v0.1.0) fix: second commit on master
* 0000010 feat: first commit on master

In this scenario, we can pretend that after your fifth commit on master you had to fix something about v0.1.0 and check out a new branch (fix_v1). After that, you committed a patch and created a new tag. (v0.1.1)

Now let's say you decided to generate a changelog for the unreleased commits. Since previous versions of git-cliff sort the tags chronologically as default, you would get something like this:

$ git cliff --unreleased

# Changelog
## [unreleased]
### Features
- Fifth commit on master

## [0.2.0] - 2021-10-22
### Features
- Fourth commit on master

### Miscellaneous Tasks
- Third commit on master

This is because --unreleased flag implicitly uses a commit range such as 0000025..HEAD, since it sorts the tags chronologically, as previously stated. This situation can now be prevented by using the --topo-order flag, which disables the automatic sorting and processes the tags as they appear in the git history:

$ git cliff --topo-order --unreleased

# Changelog
## [unreleased]
### Features
- Fifth commit on master

Now, the correct range of commits (0000040..HEAD) is processed. In other words, v0.2.0 is accepted as the latest tag in the master branch.

Tracking issue: #29

--include-path && --exclude-path​

--include-path <PATTERN>... : Sets the path to include related commits --exclude-path <PATTERN>... : Sets the path to exclude related commits

Let's say you have a monorepo and you want to generate a changelog that includes or excludes some commits that concern certain files/directories in the working directory. To explain it further, let's think that you have the following directory structure:

Cargo.toml
apps/
└── application-related files
libs/
└── library files
other/
└── miscellaneous files

In the previous versions of git-cliff, it was possible to only include commits in the changelog if the changes are against a path under e.g. "apps". This could be done by using the --commit-path argument. But now, functionality is extended much further and you can specify multiple paths, use glob patterns and even exclude files/directories by using the brand new --include-path and --exclude-path arguments.

# include commits related to any TOML file and also application directory
$ git cliff --include-path "**/*.toml" --include-path "apps/*"

# exclude commits that are related to miscellaneous files
$ git cliff --exclude-path "other/*"

With this change, --commit-path argument is removed replaced with --include-path which supports glob patterns.

Tracking issue: #34

--current​

--current: Processes the commits that belong to the current tag

Let's suppose this situation:

  1. First, v0.10.0 is released.
  2. After that, v0.11.0 is released.
  3. After that, a bug was found and v0.10.1 is released.

The problem is was, when you check out to a tag and try to generate a changelog for the latest tag, it always points out to the most recent tag (which is v0.10.1 in our example). So how do you generate changelog for the currently checked out tag? Well, simple:

$ git checkout v0.11.0

# changelog is generated for v0.11.0
$ git cliff --current

# changelog is generated for v0.10.1
$ git cliff --latest

--current flag behaves the same as running the following git command:

$ git describe --tags $(git rev-parse HEAD)

So it is expected to always use the current tag if it exists.

Tracking issue: #37

ignore_tags​

A new configuration file entry makes an appearance in the [git] section!

[git]
ignore_tags = "v.*-beta.*"

The simplest explanation would be: while skip_tags drop commits from the changelog, ignore_tags include ignored commits into the next tag.

So for example if you have the following git history:

* 2d77bc3 (HEAD -> master, tag: v0.2.0) feat: add feature 3
* 072eba9 (tag: v0.2.0-beta.1) feat: add feature 2
* 656564c (tag: v0.1.0) feat: fix feature 1
* 9d98e6b feat: add feature 1
* 6807c82 (tag: v0.1.0-beta.1) feat: add skip feature
* 93d62ef Initial commit

Setting ignore_tags = "v.*-beta.*" in the configuration will result in a changelog like this:

# Changelog
## [0.2.0] - 2021-01-23
### Features
- Add feature 2
- Add feature 3

## [0.1.0] - 2021-01-23
### Features
- Add feature 1
- Fix feature 1

Thanks to @kenji-miyake for reporting/implementing this!

Tracking issue: #36

Sorting configuration​

Following values can be specified in the configuration file now (in [git] section):

For example:

[git]
topo_order = false
sort_commits = "newest"

Tracking issue: #31

filter_unconventional​

With this new configuration file entry, it is now possible to have both conventional and unconventional commits in the changelog.

[git]
# parse conventional commits
conventional_commits = true

# do not skip unconventional commits
filter_unconventional = false

# instead, override the group and scope of unconventional commits as "Other".
commit_parsers = [
{ message = ".*", group = "Other", default_scope = "other"},
]

Other use cases of filter_unconventional are the following:

# allow only conventional commits (default)
[git]
conventional_commits = true
filter_unconventional = true

# allow any type of commit in the changelog without parsing
[git]
conventional_commits = false
filter_unconventional = false

There is also a new field called conventional added to the template context. It can be used like this in the templates:

{% if commit.conventional %} βœ… {% else %} ❌ {% endif %}

--with-commit​

--with-commit <MSG>... : Sets custom commit messages to include in the changelog

In some cases, you might want to include commit messages in the changelog that yet don't exist. One example would be having "the commit message that updates the changelog" in the changelog. (πŸ€”)

git cliff -o CHANGELOG.md
git add CHANGELOG.md
git commit -m "chore(release): update CHANGELOG.md for 1.0.0"

In the example above, CHANGELOG.md will not have the latest commit message since the commit is created afterward. So if you want to include custom commit messages like that in the changelog, you can use the --with-commit argument as follows:

# define the commit message
commit_msg="chore(release): update CHANGELOG.md for 1.0.0"

# generate changelog and pretend a commit exists as "$commit_msg"
git cliff --with-commit "$commit_msg" -o CHANGELOG.md

# create the actual commit
git add CHANGELOG.md
git commit -m "$commit_msg"

Better error messages​

git-cliff now outputs more explanatory error messages about templates, instead of just saying "Failed to parse template":

$ git cliff

ERROR git_cliff > Template parse error:
--> 3:12
|
3 | {% endif %}{% forx group, commits in commits | group_by(attribute="group") %}␊
| ^---
|
= expected end of input or some content

Looking forward​

For the future versions of git-cliff,

  • I'm planning to improve performance by parallelizing the computations using rayon. There is not a tracking issue yet, but feel free to create one and share your thoughts!
  • Benchmarking would be cool to reveal the performance as well as performance-related issues.
  • Why not add a manpage?

Contributions​

Any contribution is highly appreciated! There are contribution guidelines for getting started. Feel free to submit issues and throw ideas! 🧠

Support​

If you liked git-cliff and/or my other projects on GitHub, consider supporting me on GitHub Sponsors or Patreon β˜•

Have a wonderful day! ⛰️