Site icon Efficient Coder

Master git-cliff: Automate Changelog Generation for Flawless Release Notes

高效码农

Say Goodbye to Manual Changelogs: Automatically Generate Beautiful Changelogs from Your Git History with git-cliff

Have you ever found yourself staring at a long list of Git commits, feeling overwhelmed when it’s time to release a new version? Manually sorting, categorizing, and formatting these commit messages to write a changelog is both tedious and prone to errors. While necessary, few people actually enjoy this process.

What if you could automate this process? What if your changelogs could write themselves directly from your Git commit history? This is exactly what git-cliff is designed to do.

What is git-cliff?

git-cliff is a command-line tool that generates beautiful, customizable changelogs from your Git history. Written in Rust, it’s distributed as a single binary file, making installation straightforward and performance efficient.

Its core capability lies in its support for the Conventional Commits specification. This means git-cliff can intelligently parse your commit messages, automatically categorize different types of commits (such as feat:, fix:, chore:, etc.), and organize them into a clear, readable document.

Simply put, as long as you write your commit messages in a consistent format, git-cliff can automatically transform them into a professional changelog, eliminating the need to manually copy and paste commit hashes.

git-cliff animation demo

Why should you try git-cliff?

Highly customizable

If you don’t like the default changelog format, that’s not a problem. Through a configuration file called cliff.toml, you can flexibly adjust almost every aspect of the output:

  • Customize header and footer content
  • Adjust how commits are grouped
  • Modify date display formats
  • Even write custom regular expressions to parse specially formatted commit messages

This gives you complete control over the final presentation of your changelog, ensuring it perfectly matches your project’s needs.

Perfect support for conventional commits

If your team has already adopted conventional commits (which is highly recommended), then git-cliff will become your valuable assistant. It understands the semantics of different commit types, automatically categorizing feat: as “Features” and fix: as “Bug Fixes,” making your changelog structure clear and easy to understand at a glance.

Filter out irrelevant commits

Not every commit needs to appear in the changelog. Through configuration, you can easily ignore certain types of commits (such as chore: or ci:), ensuring the final generated log only contains changes that are actually relevant to your users.

Smart content prepending

By default, git-cliff adds newly generated changelog content to the top of your CHANGELOG.md file—exactly where you want your latest release notes to appear.

How to install git-cliff?

Installing git-cliff is straightforward, and you can do it in several ways.

Using package managers

If you’re using macOS or Linux, we recommend using Homebrew:

brew install git-cliff

Windows users can install via Scoop:

scoop install git-cliff

Manual binary download

You can also download pre-compiled binaries directly from the GitHub Releases page, then use them after extraction.

Building from source

If you prefer to build from source, make sure you have the Rust toolchain installed, then run:

cargo install git-cliff

Getting started quickly

After installation, navigate to your Git project directory and run the following command:

git cliff --latest

This command will generate changelog content based on the most recent Git tag. If you want to output directly to your CHANGELOG.md file, add the output parameter:

git cliff --latest -o CHANGELOG.md

To better adapt to your project, we recommend creating a cliff.toml configuration file. The official documentation provides rich configuration examples to help you get started quickly.

Configuration example: Customizing your changelog

Here’s a simple cliff.toml configuration example for customizing headers and commit grouping:

[changelog]
header = "# Changelog"
body = """
## [{{ version }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | upper_first }}
{% endfor %}
{% endfor %}
"""

With configuration like this, you can define version titles, date formats, group headings, and more, making the changelog completely match your project’s style.

Community and resources

Editor support

  • git-cliff.el – Generate, update and release changelog in Emacs

Similar/related projects

  • git-journal – The Git Commit Message and Changelog Generation Framework
  • clog-cli – Generate beautiful changelogs from your Git commit history
  • relnotes – A tool to automatically generate release notes for your project
  • cocogitto – A set of CLI tools for the conventional commit and semver specifications
  • cliff-jumper – A NodeJS CLI tool that combines git-cliff with conventional-recommended-bump
  • release-plz – Release Rust packages from CI
  • git-changelog-command-line – Generate changelog and determine next version with conventional commits
  • git-changelog: Automatic Changelog generator using Jinja2 templates

Frequently asked questions (FAQ)

Will git-cliff overwrite my manually written changelog?

By default, git-cliff adds new content to the top of existing files and won’t overwrite previously manually written content. You can still preserve your manually created historical entries.

What if my commit messages don’t follow conventional commit specifications?

git-cliff can still process non-standard commit messages, but it might not categorize them correctly. You can configure custom regular expressions to parse specifically formatted commit messages.

Does it support mono-repos?

Yes, git-cliff supports use in mono-repos. You can configure it to specify subdirectories or filter commits from specific paths.

Can it run automatically in CI/CD pipelines?

Absolutely. You can integrate git-cliff into GitHub Actions, GitLab CI, or other continuous integration tools, making it automatically update changelogs when new tags are released.

Can I output content in Chinese or other languages?

Yes, through custom templates, you can set changelog titles, group names, and other content to Chinese or any other language.

Social channels

Join the community discussion on these platforms:









License and copyright

git-cliff is licensed under either of Apache License Version 2.0 or The MIT License at your option.

Copyright © 2021-2025, git-cliff contributors

Conclusion

git-cliff is a tool that can significantly improve project maintenance efficiency. It fully leverages the advantages of conventional commits, transforming standardized commit messages into well-structured, beautifully professional changelogs, reducing errors and repetitive work caused by manual operations.

If you value your project’s transparency and maintainability, and want to provide clear change records for your users, then git-cliff is definitely worth incorporating into your development workflow. Try using it in your next release cycle, and you’ll discover how effortless changelog generation can be.

Exit mobile version