orhun/git-cliff

Project overview

git-cliff is a Rust-based command-line tool that turns Git history into a changelog file. It can interpret Conventional Commits and also accepts regex-powered custom commit parsers, so teams that do not follow a strict convention can still filter and group commits. The output is controlled through a configuration file and templates, allowing the changelog format to match an existing release-notes style rather than a fixed layout. It is aimed at maintainers who want repeatable, version-controlled changelog generation instead of manually editing a CHANGELOG file.

The official site and documentation cover installation, usage examples, configuration, and templating docs. There is also a separate git-cliff-core library crate for Rust integration docs.rs.

Quick start

Prerequisites: a Git repository with commit history, and git-cliff installed through one of the methods in the installation guide. Rust users can install from crates.io; prebuilt binaries and Docker images are also published.

From the root of the repository you want to document:

git-cliff --output CHANGELOG.md

This reads the repository history and writes the generated changelog to CHANGELOG.md. If the default template does not fit, create a configuration file and pass it explicitly, then iterate on the template and parser rules described in the configuration and templating documentation configuration and templating. More complete command variants are shown in the usage examples.

Usage constraints

The quality of the generated changelog depends on how well commit messages match the configured parser rules. Conventional Commits enable structured grouping, but they are not mandatory if custom regex parsers are defined. The template and output format are configuration-driven, so a usable result generally requires some initial configuration work. The project is distributed under Apache-2.0 or MIT, at the user's option license.

HotRepo's take

On the 2026-11-06 Rust daily ranking, git-cliff recorded 111 new stars and a best position of 7, showing continued attention in the Rust ecosystem. An earlier Hacker News thread from 2021 drew 223 points and 51 comments HN discussion; commenters debated whether auto-generated changelogs are better than nothing and whether Conventional Commits are well specified comment. Those are opinions from the thread, not measured project outcomes, but they point to the main trade-off: the tool works best when commit conventions or parser rules are deliberately maintained.