git-cliff: Automatically Generate Changelog Files from Git History

git-cliff generates changelog files from Git history by parsing normal commit records or using regex‑based custom parsers, allowing the changelog template to be customized via a configuration file to match the desired format.

Similar projects include git-journal, clog-cli, relnotes, and cocogitto.

Project URL: https://github.com/orhun/git-cliff

Installation

From crates.io

cargo install git-cliff

Using pacman

pacman -S git-cliff

Build from source

# linux 下依赖 zlib，生成的文件存放在 `target/release/git-cliff` 目录
CARGO_TARGET_DIR=target cargo build --release

Usage

Command format

git-cliff [FLAGS] [OPTIONS] [RANGE]

Examples

Generate a default configuration file:

git cliff --init

Generate a changelog in the project root:

# 等价于 `git-cliff --config cliff.toml --repository .`
# 等价于 `git-cliff --workdir .`
git cliff

Tag a release:

git cliff --tag 1.0.0

Generate a changelog for a specific range or tag:

# 为 latest tag 生成 changelog
git cliff --latest

# 为未发布的内部生成 changelog
git cliff --unreleased
git cliff --unreleased --tag 1.0.0

# 为指定的某个 commit 生成 changelog
git cliff 4c7b043..a440c6e
git cliff 4c7b043..HEAD
git cliff HEAD~2..

Generate a changelog for a specific directory:

git cliff --commit-path project1/

Save the changelog to a file:

git cliff --output CHANGELOG.md

Prepend new changes to an existing changelog:

git cliff --unreleased --tag 1.0.0 --prepend CHANGELOG.md

Configuration File

The configuration file supports TOML (preferred) and YAML formats. If $HOME/git-cliff/cliff.toml exists, it is read; locations differ per platform (Linux, Windows, macOS).

changelog section

[changelog]
header = "Changelog"
body = ""
trim = true
footer = "
"

header – title of the changelog

body – template for the changelog body

trim – removes leading/trailing whitespace when true

footer – footer text for the changelog

git section

[git]
conventional_commits = true
commit_parsers = [
    { message = "^feat", group = "Features" },
    { message = "^fix", group = "Bug Fixes" },
    { message = "^doc", group = "Documentation" },
    { message = "^perf", group = "Performance" },
    { message = "^refactor", group = "Refactor" },
    { message = "^style", group = "Styling" },
    { message = "^test", group = "Testing" },
]
filter_commits = false
tag_pattern = "v[0-9]*"
skip_tags = "v0.1.0-beta.1"

When conventional_commits is true, commits are parsed according to the Conventional Commits specification ( link ), which provides a lightweight convention for clear commit histories and aids automated tooling.

Commit parsers use regular expressions to group commits, e.g., messages starting with feat are grouped under "Features"; commits containing "security" in the body are grouped under "Security"; and commits marked with revert are skipped.

Additional options include filter_commits to exclude non‑matching commits, tag_pattern for matching tag names (e.g., v[0-9]* ), and skip_tags to ignore specific tags.