git-cliff

Generate changelogs from git history

TLDR

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

$ git cliff > [CHANGELOG.md]

Generate a changelog from commits starting from the latest tag and print it to stdout

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

Generate a changelog from commits that belong to the current tag (use git checkout on a tag before this)

$ git cliff --current

Generate a changelog from commits that do not belong to a tag

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

Write the default config file to cliff.toml in the current directory

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

-o, --output
    Write the generated changelog to FILE instead of standard output.

-c, --config
    Specify a custom path to the configuration file (default is cliff.toml).

-f, --force
    Overwrite the output file if it already exists without prompting.

-s, --sort
    Sort commits by newest or oldest date within each section.

-t, --tag
    Generate the changelog for changes associated with a specific TAG.

-l, --latest
    Generate the changelog for changes since the latest Git tag.

-u, --unreleased
    Generate the changelog for all unreleased changes (since the last tag).

-p, --prepend
    Prepend the new changelog content to an existing output file.

--init
    Create a boilerplate cliff.toml configuration file in the current directory.

--help
    Display help information for the command.

--version
    Display the version information for git-cliff.

DESCRIPTION

git-cliff is a fast and highly customizable changelog generator that reads your Git history and produces a structured changelog. It is designed to work seamlessly with the Conventional Commits specification, extracting information such as commit types (features, fixes, etc.), scopes, and breaking changes to organize your releases effectively. The tool provides extensive templating capabilities, allowing users to define the exact format and content of their changelogs using a TOML configuration file (cliff.toml). This makes it suitable for various project types and release workflows, ensuring consistency and automation in documentation.

CAVEATS

Requires Conventional Commits: While highly configurable, git-cliff's full power and structured output are best realized when your Git commit history adheres to the Conventional Commits specification.
Configuration Complexity: For highly customized changelog outputs, the cliff.toml configuration file can become quite complex, requiring familiarity with TOML and templating syntax.

CONFIGURATION FILE (<CODE>CLIFF.TOML</CODE>)

git-cliff is highly configurable via a cliff.toml file. This file allows users to define how commits are parsed, how sections are grouped (e.g., features, bug fixes, breaking changes), customize the output template using Jinja2-like syntax, and filter commits based on types, scopes, or tags. This makes it incredibly flexible for diverse project requirements.

CONVENTIONAL COMMITS SUPPORT

The tool is built with a strong emphasis on the Conventional Commits specification. It automatically understands commit types like feat, fix, chore, docs, refactor, perf, test, and build, and can extract scopes and breaking changes messages to generate a semantically versioned changelog.

HISTORY

git-cliff was initially created by Orhun Parmaksız and first released around late 2021 (version 1.0.0 in November 2021). It emerged as a modern, Rust-based alternative to existing changelog generators, focusing on performance, extensibility, and strict adherence to the Conventional Commits specification. Its development has been community-driven, with continuous improvements in templating, filtering, and configuration options, making it a popular choice for automated release workflows.