git-cliff - Customizable Changelog Generator

git-cliff - Customizable Changelog Generator

Research Date: January 26, 2026 Source URL: https://git-cliff.org GitHub Repository: https://github.com/orhun/git-cliff Documentation: https://git-cliff.org/docs Version at Research: v2.12.0 License: Apache-2.0 / MIT (dual-licensed)

Overview

git-cliff is a highly customizable changelog generator that creates structured changelogs from Git history using conventional commits and regex-powered custom parsers. Built in Rust for performance, it supports multiple output formats through Tera templating and integrates with GitHub, GitLab, Gitea, and Bitbucket for remote metadata enrichment.

Core Value Proposition: Transform Git commit history into professional, customizable changelogs with zero manual effort, supporting both conventional commits and custom parsing rules.

Problem Addressed

Key Statistics (as of January 26, 2026)

Key Features

1. Conventional Commits Support

• Standard Prefixes: feat:, fix:, docs:, refactor:, chore:, etc.
• Scopes: Support for feat(parser): style scoped commits
• Breaking Changes: Detect ! suffix (e.g., feat!:) and BREAKING CHANGE: footers
• SemVer Correlation: Automatic mapping to major/minor/patch versions

2. Custom Commit Parsers

• Regex-Powered: Define custom patterns for non-conventional commits
• Group Mapping: Map any commit pattern to changelog groups
• Skip Patterns: Filter out commits that shouldn't appear in changelog
• Field Extraction: Extract custom fields from commit messages

3. Templating System (Tera)

• 10+ Built-in Templates: Basic, Keep a Changelog, GitHub, Minimal, Detailed, Scoped, etc.
• Custom Templates: Full Tera template language support
• Conditional Logic: Include/exclude sections based on content
• Emoji Support: Optional emoji prefixes for visual categorization

4. Remote Integration

• GitHub: PR titles, numbers, authors, labels as grouping keys
• GitLab: Merge request metadata
• Gitea: Self-hosted Git forge support
• Bitbucket: Bitbucket PR integration

5. Output Modes

• Full Changelog: Complete history from first commit
• Latest Release: Only changes since last tag
• Unreleased: Changes since last tag (for pre-release)
• Range: Specific commit range (e.g., v1.0.0..HEAD)
• Prepend: Update existing changelog with new entries

6. Monorepo Support

• Path Filtering: Generate changelogs for specific directories
• Include/Exclude Paths: Fine-grained control over which changes appear
• Per-Package Changelogs: Separate changelogs for monorepo packages

7. Configuration

• TOML/YAML: Configuration file support
• Environment Overrides: Override any config via environment variables
• Global Config: User-level defaults at ~/.config/git-cliff/cliff.toml
• Project Config: Repository-level cliff.toml

Technical Architecture

Git Repository
      │
      ▼
┌─────────────────────────────────────────┐
│           git-cliff CLI                  │
│  ┌─────────────────────────────────┐    │
│  │      Commit Parser               │    │
│  │  - Conventional commits          │    │
│  │  - Custom regex patterns         │    │
│  │  - Scope extraction              │    │
│  └─────────────────────────────────┘    │
│                  │                       │
│                  ▼                       │
│  ┌─────────────────────────────────┐    │
│  │      Remote Metadata             │    │
│  │  - GitHub API                    │    │
│  │  - GitLab API                    │    │
│  │  - PR titles, authors, labels    │    │
│  └─────────────────────────────────┘    │
│                  │                       │
│                  ▼                       │
│  ┌─────────────────────────────────┐    │
│  │      Template Engine (Tera)      │    │
│  │  - Built-in templates            │    │
│  │  - Custom templates              │    │
│  │  - Conditional rendering         │    │
│  └─────────────────────────────────┘    │
│                  │                       │
│                  ▼                       │
│  ┌─────────────────────────────────┐    │
│  │      Output Formatter            │    │
│  │  - Markdown                      │    │
│  │  - JSON                          │    │
│  │  - Prepend/overwrite modes       │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
      │
      ▼
CHANGELOG.md / stdout / JSON

Installation & Usage

Installation Options

# Cargo (Rust)
cargo install git-cliff

# Homebrew (macOS/Linux)
brew install git-cliff

# Arch Linux
pacman -S git-cliff

# NPM
npm install -g git-cliff

# Docker
docker run -t -v "$(pwd)":/app/ orhunp/git-cliff

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

Basic Usage

# Initialize configuration
git-cliff --init

# Generate full changelog
git-cliff -o CHANGELOG.md

# Generate for latest release only
git-cliff --latest

# Generate unreleased changes with tag
git-cliff --unreleased --tag 1.0.0

# Prepend to existing changelog
git-cliff --unreleased --tag 1.0.0 --prepend CHANGELOG.md

Configuration Example (cliff.toml)

[changelog]
header = """
# Changelog\n
All notable changes to this project will be documented in this file.\n
"""
body = """
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {% if commit.scope %}*({{ commit.scope }})* {% endif %}{{ commit.message | upper_first }}
    {% endfor %}
{% endfor %}
"""
footer = """
<!-- generated by git-cliff -->
"""

[git]
conventional_commits = true
filter_unconventional = 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" },
    { message = "^chore\\(release\\)", skip = true },
]

GitHub Integration Example

[remote.github]
owner = "orhun"
repo = "git-cliff"
token = "" # or use GITHUB_TOKEN env var

[changelog]
body = """
## What's Changed
{% for commit in commits %}
* {{ commit.message }} by @{{ commit.github.username }} in #{{ commit.github.pr_number }}
{% endfor %}
"""

Output Template Examples

Keep a Changelog Format

# Changelog

## [Unreleased]

### Added
- Support multiple file formats

### Changed
- Use cache while fetching pages

## [1.0.1] - 2021-07-18

### Added
- Add release script

### Changed
- Expose string functions

GitHub Release Format

## What's Changed
* feat(cache): use cache while fetching pages by @orhun
* feat(config): support multiple file formats by @orhun

**Full Changelog**: https://github.com/owner/repo/compare/v1.0.0...v1.0.1

Relevance to Claude Code Development

Direct Applications

1. Commit Message Skill: Use git-cliff's conventional commit parsing as reference for commit message validation/generation
2. Release Automation: Integrate into plugin release workflows for automatic changelog generation
3. Monorepo Support: Pattern for per-plugin changelogs in multi-plugin repositories
4. GitHub Integration: PR metadata enrichment patterns applicable to code review workflows

Patterns Worth Adopting

1. Conventional Commits: Standardized commit format improves AI comprehension of changes
2. Regex-Based Parsing: Flexible pattern matching for extracting structured data from text
3. Template-Driven Output: Tera templating pattern for customizable AI-generated content
4. Prepend Mode: Incremental update pattern preserving existing content
5. Environment Overrides: Configuration hierarchy (global → project → environment)

Integration Opportunities

1. commit-staged skill: Could validate commits follow conventional format before generation
2. push skill: Auto-generate changelog entries on push
3. Plugin releases: Automate CHANGELOG.md generation for plugin marketplace
4. PR descriptions: Generate "What's Changed" sections from commit history

Key Insight

git-cliff demonstrates that structured commit messages (conventional commits) enable powerful automation. This principle applies to Claude Code: structured, consistent formats in skills, agents, and commands enable better tooling and AI comprehension.

References

1. Official Website: https://git-cliff.org (accessed 2026-01-26)
2. GitHub Repository: https://github.com/orhun/git-cliff (accessed 2026-01-26)
3. Documentation: https://git-cliff.org/docs (accessed 2026-01-26)
4. Configuration Guide: https://git-cliff.org/docs/configuration (accessed 2026-01-26)
5. Template Examples: https://git-cliff.org/docs/templating/examples (accessed 2026-01-26)
6. Usage Examples: https://git-cliff.org/docs/usage/examples (accessed 2026-01-26)
7. Conventional Commits Specification: https://www.conventionalcommits.org/
8. Keep a Changelog: https://keepachangelog.com/
9. Tera Template Engine: https://keats.github.io/tera/

Related Tools

Freshness Tracking

Change Detection Indicators:

• Monitor GitHub releases for version changes
• Check crates.io for new versions
• Review changelog for new template formats
• Track new remote integrations (Forgejo, etc.)
• Watch for breaking changes in cliff.toml schema