git-cliff

A changelog generator that parses conventional commits and produces beautifully formatted CHANGELOG files using customizable Tera templates. Written in Rust. Works with any language ecosystem.

What is git-cliff?

git-cliff is a changelog generator that reads your Git history, parses commit messages following the Conventional Commits specification, and renders a formatted changelog using the Tera templating engine. It is language-agnostic, written in Rust, and configured via a cliff.toml file that lives in your repository root.

Unlike tools such as standard-version that couple changelog generation with version bumping, git-cliff focuses purely on the changelog. This makes it flexible: use it standalone, as part of a release script, or via GitHub Actions to auto-generate release notes when you push a tag.

Key Features

• Conventional commits parsing — categorizes feat, fix, perf, refactor, docs, and more into changelog sections
• Tera templating — full Jinja2-compatible template syntax for any output format (Markdown, AsciiDoc, HTML)
• Tag range support — generate changelogs for specific version ranges, latest release, or unreleased commits
• cliff.toml configuration — commit parsers, skip patterns, tag patterns, body template, and header all configurable
• GitHub Actions integration — official action for automated changelog on tag push
• Prepend mode — prepend new release notes to an existing CHANGELOG.md, building a cumulative file
• Scope grouping — group commits by conventional commit scope (e.g., feat(auth):, fix(api):)
• Breaking change highlighting — automatically surfaces BREAKING CHANGE commits in a separate section

Installation

# macOS (Homebrew)
brew install git-cliff

# Rust / Cargo (any platform)
cargo install git-cliff

# Windows (Scoop)
scoop install git-cliff

# npm (for Node.js projects)
npm install --save-dev git-cliff

# Download binary from GitHub Releases
# https://github.com/orhun/git-cliff/releases

Basic Usage

# Generate full changelog to stdout
git cliff

# Write to CHANGELOG.md
git cliff -o CHANGELOG.md

# Generate only unreleased changes
git cliff --unreleased

# Generate only the latest release's changes
git cliff --latest

# Generate changelog for a tag range
git cliff v1.0.0..v2.0.0

# Tag the current HEAD and generate with that version
git cliff --tag v1.2.3 --unreleased

# Init a default cliff.toml in the current directory
git cliff --init

Example cliff.toml

[changelog]
header = """
# Changelog

All notable changes to this project will be documented in this file.
"""
body = """
{% if version %}\
    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}\
    ## [Unreleased]
{% endif %}\
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | striptags | trim | upper_first }}
    {% for commit in commits %}
        - {% if commit.scope %}*({{ commit.scope }})* {% endif %}{{ commit.message | upper_first }}\
    {% endfor %}
{% endfor %}\
"""
trim = true

[git]
conventional_commits = true
filter_unconventional = true
commit_parsers = [
    { message = "^feat", group = "Features" },
    { message = "^fix", group = "Bug Fixes" },
    { message = "^perf", group = "Performance" },
    { message = "^refactor", group = "Refactoring" },
    { message = "^docs", group = "Documentation" },
    { message = "^chore|^ci|^test", skip = true },
]
filter_commits = true
tag_pattern = "v[0-9].*"

Conventional Commits Quick Reference

Use Cases

• Auto-generating CHANGELOG.md on every tagged release via GitHub Actions
• Producing GitHub Release notes from the latest tag's commits
• Enforcing conventional commits in a team by making the changelog meaningful and automated
• Generating release notes in custom formats (AsciiDoc, HTML, JSON) for documentation systems
• Auditing what changed between two versions during incident investigation

Pros and Cons