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 big 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:
- The numbers in commit messages are replaced with
<REPO>/issues/<num>with the help of git.preprocessors. - The changelog is generated using changelog.body which has a couple of
<REPO>usages. <REPOis 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 needgit-cliffto 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! π
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.
- Dates: November 19th -> November 21th
- Location: Florence, Italy
- Tickets: https://rustlab.it/tickets
Contributionsβ
Any contribution is highly appreciated! There are contribution guidelines for getting started.
Feel free to submit issues and join Discord / Matrix!
Donateβ
If you liked git-cliff and/or my other projects on GitHub, consider donating to support my open source endeavors.
Have an awesome day! β°οΈ