git-cliff

Generate a changelog from all commits in a Git repository and save it to CHANGELOG.md

$ git cliff > [CHANGELOG.md]

$ git cliff [[-l|--latest]]

$ git cliff --current

$ git cliff [[-u|--unreleased]]

$ git cliff [[-i|--init]]

git-cliff [OPTIONS] [<PATH>]

-h, --help
    Print help information

-V, --version
    Print version information

-u, --unstable
    Enable unstable features

-c, --config <PATH>
    Set configuration file

-o, --output <PATH>
    Write output to file

-p, --prepend <PATH>
    Prepend changelog to file

-a, --append <PATH>
    Append changelog to file

-l, --length <NUM>
    Limit changelog to NUM entries

--print-config
    Print default configuration

--tag <TAG>
    Changelog starting tag

--start-tag <TAG>
    Starting tag (deprecated)

--end-tag <TAG>
    Ending tag

--current-tag <TAG>
    Current tag name

--previous-tag <TAG>
    Previous tag name

--include-path <GLOB>
    Include paths matching glob

--exclude-path <GLOB>
    Exclude paths matching glob

--merge-commit-end
    End changelog at merge commit

--sort-commits <ORDER>
    Sort commits (oldest, newest)

--date-order
    Sort by date instead of topo-order

--commit-id-length <LEN>
    Shorten commit ID to LEN chars

-b, --body-max-lines <NUM>
    Limit commit body lines

--footer-max-lines <NUM>
    Limit commit footer lines

--field-max-lines <NUM>
    Limit custom fields lines

--break-on-unmatched <BREAK>
    Handle unmatched commits

--github-token <TOKEN>
    GitHub token for API

--github-repo <REPO>
    GitHub repo owner/repo

--github-release
    Create GitHub release

git-cliff is a command-line tool written in Rust for generating changelogs from Git commit history.

It excels in speed, processing large repositories (e.g., Linux kernel) in seconds, and offers extensive customization via TOML configuration files.

Key features:
• Support for Conventional Commits and custom parsers.
• Flexible filtering by paths, tags, and merge commits.
• Jinja2-like templating for output formatting.
• Integration with GitHub Releases and other CI/CD pipelines.
• Options for sorting commits, limiting lengths, and multi-section grouping (e.g., Added, Fixed, Breaking).

Usage typically involves running it in a Git repo root with a config defining sections, parsers, and templates. It extracts commit metadata (subject, body, footer), matches against rules, groups by type/date/tag range, and renders to stdout or file.

Popular in open-source for automating CHANGELOG.md updates, outperforming slower alternatives in performance and flexibility.

Requires a Git repository; complex configs have learning curve.
Does not auto-install dependencies like git.
Unstable flag enables experimental features that may break.

Via Cargo: cargo install git-cliff
Packages: Arch (git-cliff), Fedora (git-cliff), Homebrew (git-cliff).

git-cliff --config cliff.toml -o CHANGELOG.md
Generates changelog using config, writes to file.

Run git-cliff --print-config > cliff.toml to generate editable template.

Developed by Orhun Parmaksız starting 2021 in Rust for speed.
First release v0.1.0 in March 2021; reached v1.0 in 2023.
Popularized via Hacker News; now used in 10k+ repos, including Rust projects.

git-log(1), git-shortlog(1), git-tag(1)