Git Cliff

12.4K stars
Apache-2.0
Active this month
Last commit 13 days ago

Last verified Nov 15, 2026

Generate changelog files from Git history using conventional commits and regex-powered custom parsers with a configurable template system.

Visit website GitHub12.4K

Read the full breakdownWho it is for, how it works, trade-offs, the quick start and the FAQ

who it's for

Who Git Cliff is for#

Open source maintainers shipping versioned releases

Git Cliff automates the CHANGELOG.md update on each release tag, feeding conventional commits from the entire history into organized sections. The maintainer runs one command before pushing a tag and gets a changelog file ready for the GitHub Release page.

Skip if:

Your release workflow depends on GitHub's automatic release notes and you have no need to maintain a CHANGELOG.md file in the repository. The platform's native notes generation may be sufficient without an additional tool.

Release engineers managing multi-contributor changelogs

In projects with many contributors, git-cliff reads the full commit history without requiring each contributor to update a changelog file manually. A single CI step on the release branch generates the changelog from whatever commits made it in, filtered by parser rules.

Skip if:

Your team does not follow Conventional Commits and has not documented commit message conventions. Without a parser config, git-cliff will not produce useful section groupings from free-form messages.

Rust projects embedding changelog generation in tooling

Git Cliff ships as the git-cliff-core library on crates.io. Rust projects that orchestrate releases programmatically can call the library directly to generate changelog content as part of a larger build or release pipeline.

Skip if:

You are building in Python, Node.js, or another language. The library integration is Rust-only; other languages use the CLI binary.

the problem

The problem it solves#

Writing and maintaining a CHANGELOG.md by hand is error-prone for any project with more than a few contributors. Commits get missed between releases, section headers drift in format, and the developer cutting a release has to scan the entire diff to piece together what changed. The result is changelogs that are either incomplete, inconsistently formatted, or simply not updated after the first release.

For teams that have adopted Conventional Commits, there is a gap between that investment and usable release notes. The spec captures intent in each commit message, but turning hundreds of prefixed commits into a readable, versioned changelog still requires a scripted or manual pass.

how Git Cliff solves it

How it solves it#

Conventional Commits Parser

Parses commit messages following the Conventional Commits specification, grouping them into changelog sections for features (feat:), bug fixes (fix:), breaking changes, and other types you configure. Any repository that follows the spec gets structured output with no extra setup.

Regex-Powered Commit Parsers

Accepts custom regex patterns for commit message parsing when Conventional Commits is not in use. Configure one or more named parsers in a config file to match your project's commit conventions and assign each match to a changelog section.

Configurable Template System

The changelog output format is controlled by a template in the config file. Adjust section headers, entry formatting, version markers, and ordering to match the Keep a Changelog spec or any custom format your project requires.

CLI Tool and Rust Library

Ships as a command-line binary for direct use in CI pipelines, and as a Rust library (git-cliff-core) for embedding changelog generation into Rust projects. The library is published on crates.io and documented at docs.rs.

CI/CD Pipeline Integration

Integrates with any CI/CD pipeline on any Git host. Install the binary or pull the Docker image at orhunp/git-cliff to add changelog generation to your release workflow without platform-specific plugins or integrations.

strengths · trade-offs

Strengths and trade-offs#

Strengths

Works with Any Git HostUnlike release notes features tied to a specific Git hosting platform, git-cliff reads the local Git history directly and works with any Git repository regardless of where it is hosted. Teams using self-hosted Git servers or non-GitHub platforms do not lose any functionality.
Apache-2.0 LicenseLicensed under Apache-2.0, git-cliff can be used freely in commercial projects and CI pipelines without licensing restrictions. No usage tiers, no API keys, and no rate limits on how many releases you generate.
Actively Maintained Since 2021Created in May 2021 with a last push in November 2026, git-cliff has 12,417 GitHub stars and 347 forks. The project runs a Discord server and Matrix channel for community support and was presented at RustLab 2023.

Trade-offs

-Requires Consistent Commit Message FormatOutput quality scales with commit message discipline. Projects using the Conventional Commits parser get organized sections only when commits follow the feat:, fix:, chore:, and other type prefixes consistently. Teams with free-form commit history need to write custom regex parsers for each pattern or accept unstructured output for older entries.
-Cargo Install Requires a Rust ToolchainThe primary documented install path uses cargo install git-cliff, which requires a Rust toolchain. For teams not working in Rust, this adds a dependency. The Docker image at orhunp/git-cliff is the alternative, though it adds container overhead for simple changelog generation tasks.

versus alternatives

Git Cliff vs alternatives#

Git Cliff vs GitHub Automatic Release Notes

GitHub includes an automatic release notes feature that generates notes from pull request titles and labels when a release is published. It is free but proprietary and limited to GitHub-hosted repositories. Git Cliff is an alternative that generates changelog content from commit messages directly, works with any Git host, and produces a versioned CHANGELOG.md file in your repository.

Feature	Git Cliff	GitHub Automatic Release Notes
License	Apache-2.0	Proprietary
Hosting requirement	Any Git host	GitHub only
Input source	Commit messages	Pull request labels
Output	CHANGELOG.md file	GitHub Release page
Conventional Commits	Yes	No

Git Cliff is the better choice when your team follows Conventional Commits, wants a CHANGELOG.md file checked into the repository, or hosts code outside GitHub. The configurable template system gives you control over output format, section grouping, and version range filtering that GitHub's native feature does not provide.

GitHub's built-in feature suits teams that organize work through pull requests with labels, publish releases directly on GitHub, and do not need a versioned CHANGELOG.md in the repository. It requires no additional tooling for teams already committed to the GitHub platform.

install · quick start

Quick start#

bash

Install git-cliff from crates.io using the Cargo package manager.
```bash
cargo install git-cliff
```

tech stack · detected from GitHub

What it's built on#

Languages: JavaScriptRustTypeScript
Frameworks: React

frequently asked

FAQ#

Does git-cliff work with repositories that don't use Conventional Commits?

Yes, with custom configuration. Git Cliff supports regex-powered commit parsers defined in its config file. Write one or more regular expressions to match your commit message format and assign each match to a changelog section. Without any parser config and without Conventional Commits, commits appear ungrouped in the output.

How do I install git-cliff?

The primary install path is via Cargo: run cargo install git-cliff after installing the Rust toolchain. A Docker image is available at hub.docker.com/r/orhunp/git-cliff for containerized environments. Full installation documentation is at git-cliff.org/docs/installation.

What license does git-cliff use?

Git Cliff is licensed under Apache-2.0. You can use it freely in commercial projects, CI pipelines, and open source workflows without restriction. The Apache-2.0 license requires preserving copyright notices and the license file in distributed copies but does not require source disclosure.

Can git-cliff be used as a library rather than a CLI tool?

Yes. The git-cliff-core crate is published on crates.io and documented at docs.rs. Rust projects can import it to run changelog generation programmatically. The CLI binary wraps the core library, so the library exposes the same parsing and templating capabilities available from the command line.

Does git-cliff integrate with GitHub Actions or other CI systems?

Git Cliff runs as a standard CLI binary and works with any CI/CD system that can install a binary or pull a Docker image. No dedicated CI plugin is required; teams commonly run it in a release workflow step triggered by a version tag push, generating the CHANGELOG.md before creating the release.

also worth a look

Similar open-source tools#

Nuphos

Featured

Alternative toConductor

Agent workspace for teams running Claude Code or Codex

529 GitHub stars
Licence Apache-2.0

Aspire

InDeveloper Tools

Code-first distributed app orchestration with built-in observability.

6,426 GitHub stars
Licence MIT

Apache SkyWalking

Alternative toDatadog

APM platform covering traces, metrics, logs, and AI agent monitoring.

25,007 GitHub stars
Licence Apache-2.0

Uptrace

Alternative toDatadog

Self-hosted APM for distributed traces, metrics, and logs.

4,314 GitHub stars
Licence AGPL-3.0

ClickStack

Alternative toDatadog

Self-hosted observability stack on ClickHouse with session replay

10,040 GitHub stars
Licence MIT

Milvaion

Alternative toHangfire Pro

Distributed .NET job scheduler, decoupled workers, one dashboard.

81 GitHub stars
Licence Apache-2.0

by category

Open source tools in these categories#

650

13,025 GitHub stars
Licence AGPL-3.0
#Email

rakazo

Alternative toGrok Bot

AI teammates you own: your keys, your model, your machine.

8,291 GitHub stars
Licence Apache-2.0
#AI Agents

SnitchFeed

Live monitoring on LinkedIn, X, Reddit & more. Agentic social listening for startups.

Marketing & Growth

Advertise your product

The projects we add and every new guide. Free, unsubscribe any time.

Find open source alternatives to paid software

Git Cliff vs GitHub Automatic Release Notes

Feature	Git Cliff	GitHub Automatic Release Notes
License	Apache-2.0	Proprietary
Hosting requirement	Any Git host	GitHub only
Input source	Commit messages	Pull request labels
Output	CHANGELOG.md file	GitHub Release page
Conventional Commits	Yes	No

Who Git Cliff is for#

Open source maintainers shipping versioned releases

Skip if:

Release engineers managing multi-contributor changelogs

Skip if:

Rust projects embedding changelog generation in tooling

Skip if:

The problem it solves#

How it solves it#

Conventional Commits Parser

Regex-Powered Commit Parsers

Configurable Template System

CLI Tool and Rust Library

CI/CD Pipeline Integration

Strengths and trade-offs#

Strengths

Trade-offs

Git Cliff vs alternatives#

Git Cliff vs GitHub Automatic Release Notes

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

Developer Tools

DevOps & CI/CD

Find open source alternatives to paid software

Who Git Cliff is for#

Open source maintainers shipping versioned releases

Skip if:

Release engineers managing multi-contributor changelogs

Skip if:

Rust projects embedding changelog generation in tooling

Skip if:

The problem it solves#

How it solves it#

Conventional Commits Parser

Regex-Powered Commit Parsers

Configurable Template System

CLI Tool and Rust Library

CI/CD Pipeline Integration

Strengths and trade-offs#

Strengths

Trade-offs

Git Cliff vs alternatives#

Git Cliff vs GitHub Automatic Release Notes

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

Developer Tools

DevOps & CI/CD

Find open source alternatives to paid software