git-cliff

git-cliff is a changelog generator that parses your Git commit history and produces a formatted CHANGELOG.md based on Conventional Commits. The output format is fully customizable via a Tera template, so you can produce Markdown, HTML, or any other text format you need.

Features

• Conventional Commits support — automatically groups commits into sections (features, bug fixes, breaking changes, etc.)
• Fully customizable — templates are written in Tera (Jinja2-compatible), giving you complete control over the output format
• Tag-based versioning — generates one section per Git tag, with unreleased changes at the top
• Remote integration — can fetch pull request metadata from GitHub, GitLab, and Gitea to enrich the changelog
• GitHub Actions support — official action available for generating changelogs in CI
• Commit filtering — skip commits by message pattern, author, or commit type
• Bump version — can suggest or apply the next semantic version based on the commits since the last tag

Installation

cargo install git-cliff

Or via your system package manager:

# macOS
brew install git-cliff

# Arch Linux
pacman -S git-cliff

# Debian / Ubuntu (Debian 12+)
apt install git-cliff

# Fedora
dnf install git-cliff

# Nix
nix-env -iA nixpkgs.git-cliff

Usage

# Generate a changelog for the entire history
git-cliff

# Output to a file
git-cliff -o CHANGELOG.md

# Generate only for unreleased commits (since the last tag)
git-cliff --unreleased

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

# Bump the version and prepend unreleased changes to an existing CHANGELOG.md
git-cliff --bump --prepend CHANGELOG.md

# Print the next semantic version that would be bumped to
git-cliff --bumped-version

# Initialise a default config file in the current directory
git-cliff --init

Configuration

git-cliff reads from cliff.toml (or [tool.git-cliff] in Cargo.toml). Initialise one with git-cliff --init, then customise it:

[changelog]
header = "# Changelog\n\n"
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.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}\
{% endfor %}
{% endfor %}\n
"""
trim = true
footer = ""

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

CI Integration

Add to your GitHub Actions workflow to auto-publish a changelog on each release:

- name: Generate changelog
  uses: orhun/git-cliff-action@v3
  with:
    config: cliff.toml
    args: --verbose
  env:
    OUTPUT: CHANGELOG.md
    GITHUB_REPO: ${{ github.repository }}