Stop Writing Changelogs Manually. Let Your Git History Do It.

You just tagged a new release. Now comes the tedious part: scouring the git log, trying to remember what changed since the last version, and formatting it all into something presentable for a changelog. We've all been there. It's a manual, error-prone process that everyone needs but no one loves to do.

What if you could automate that? What if your changelogs could write themselves, directly from your commit history?

What is git-cliff?

git-cliff is a command-line tool that generates beautiful, customizable changelogs from your Git history. It’s built in Rust, which means it's fast and installs as a single binary. The real magic, though, is that it follows the Conventional Commits specification. This means it can intelligently parse your commit messages, categorize changes (like feat:, fix:, chore:), and structure them into a clean, readable document.

In short, you commit using a consistent format, and git-cliff turns that history into a professional changelog. No more copying and pasting commit hashes.

Why It's Cool

The beauty of git-cliff isn't just that it automates a boring task—it's how well it does it.

• Highly Customizable: Don't like the default format? No problem. You can tweak everything using a cliff.toml configuration file. Change the header, footer, the way commits are grouped, the date format, and even use custom regular expressions to parse specialized commit messages.
• Conventional Commits FTW: If your team has adopted Conventional Commits (and you should!), git-cliff is the perfect companion. It understands the semantics of your commits, so a feat: becomes a "Features" section and a fix: becomes a "Bug Fixes" section.
• Skip the Noise: It can be configured to ignore certain commits (like chore: or ci:), so your changelog only contains the changes that are actually relevant to your users.
• Prepends for the Win: By default, it writes the new changelog entries to the top of your CHANGELOG.md file, which is exactly where you want your latest release notes to be.

How to Try It

Getting started is straightforward. You can install git-cliff via package managers, download a pre-built binary, or build it from source.

The quickest way on macOS and Linux is often via a package manager. For example, with Homebrew:

brew install git-cliff

Or on Windows with Scoop:

scoop install git-cliff

You can also grab the latest binary directly from the GitHub Releases page.

Once installed, navigate to your Git repository and run:

git cliff --latest

This will generate a changelog for the most recent tag. To output it to your CHANGELOG.md file, use:

git cliff --latest -o CHANGELOG.md

For the best results, you'll want to create a cliff.toml file to configure it for your project's needs. The project's README has excellent examples to get you started.

Final Thoughts

git-cliff is one of those tools that feels like a no-brainer once you start using it. It takes a best practice (structured commit messages) and maximizes its value by automating the final deliverable: the changelog. It removes the friction and human error from the release process, making it easier to keep your users and team members informed.

If you're serious about maintaining a clear and consistent project history, it's absolutely worth integrating into your workflow. Your future self, during the next release, will thank you.

—

Follow us for more cool projects: @githubprojects