Git-cliff – Generate changelog from the Git history

I'm not a big fan of auto generated commit logs - they just have too much noise in. You might as well look at the git history. Changelogs should be for users to read.

I have a program which generates the first draft of the rclone changelog from the first line of each git commit. I try to encourage all contributors to make the first line of their commit message be something a user would like to read in the changelog. Instead of `fixed nil pointer error` have `fixed crash when copying file to xyz backend`.

https://rclone.org/changelog/

I also spend maybe an hour each release editing the auto generated changelog, removing the noise (refactored X, fixed docs for Y, made tests for Z work), condensing multiple entries, reorganizing, moving things to the correct section, linking stuff etc. Where the committer didn't write a sensible first line commit message I go back look at the diff and rewrite it.

I try to put the important things first in the changelog and keep it brief. The changelog is a heads-up for users that things have changed or been fixed and users don't want to spend hours reading it.

I think for an open source project like rclone where I review commits from all different levels of developer, and from all different levels of English mastery I'd have too much difficulty getting every commit message written in https://www.conventionalcommits.org/en/v1.0.0/ style to use a tool like git-cliff to generate the changelog without editing it.

Would I like not to spend an hour or more of my time editing the changelog for each release - most definitely! However I owe it to the users to make something nice and I don't think I can delegate that to a program.

I am definitely more in the changelog-as-a-file camp. From https://keepachangelog.com/:

> Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

> The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don't.

> The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.

Here's an example of a changelog that is generated using git-cliff: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.m...

The things that make this work well for us are

- We make sure we document every PR with user facing language and conventional commits.

- We generally use GitHub's squash merge, which means the noisy development commits are not part of the changelog.

- We create a highlights doc when we release that summarizes the main points of the changelog (this is the distinction between a changelog and release notes). E.g. https://ratatui.rs/highlights/v027/

I've seen quite a few projects lately that are generating their release notes from commit history. This is quite *bad* because it's frequently full of things that are inconsequential for users. I really don't care that you refactored your foo-baz into a qux-quz. Please at least summarize the major points between releases.

Hopefully this software is better but this seems like an opportune place to lodge this complaint.

I maintain git-changelog, which is a similar implementation in Python (started two years before git-cliff). When I discovered git-cliff a few months ago, I was very impressed by the number of things they support. Also, being written in Rust, it must be much more performant than my Python implementation (which indeed has trouble with huge Git histories). I have started recommending git-cliff to some of my users who request features I don't yet support :)

Great work, git-cliff devs!

I don't quite understand the use case for this sort of app (generating a nice changelog from a well structured commit history.) In my experience if your team is disciplined enough to use something like Conventional Commit rigorously you don't actually need an app. The history of the merge commits or pull request descriptions is usually enough, unless you're passing the changelog to particularly non-technical users, in which case you need a human to write the changelog regardless.

For an app to be useful you need to have a case where you want the data from the commit history to be useful in the context of a doc, where you retain technical descriptions written by devs. Just copying the commit descriptions into a doc, even in a nicer format, feels like theatre to me. You aren't gaining anything. Non-technical users won't benefit from it and everyone else can learn 'git log'.

There is an arguement that using this would push a dev team to improve their commits, but in my experience if the team lack enough discipline to write them well a time saving tool isn't enough to push them to get better. They're probably not writing a useful changelog yet, so this doesn't save any time at all.

I really hope I'm missing something.

What other comments are missing is that git-cliff is based on the conventional commits [1] spec.

If you follow this properly the commits will already have important metadata for presentation in a changelog.

Also keep in mind that the auto-generated changelog should always be augmented and filtered manually before the final release.

But the combination of git-cliff and conventional commits can save a lot of time for the initial draft.

It does require discipline in using conventional commits properly.

[1] https://www.conventionalcommits.org/en/v1.0.0/

We built an internal system that grabs our git history. For each commit you either enter a release note or mark it as not customer facing. It’s worked pretty well so far: each developer runs through their list writing down something, and a technical writer follows up checking style and grammar. We have confidence that every commit was at least looked at.

We do monthly releases, and the level of effort has been under an hour each month per dev, which has been super worth it for us.

16 clicks to get to the examples in the documentation. I think you could do a much better job of organizing and showcasing how this tool works before so much about how to install it on every platform.

I use git-cliff for my personal projects. If you follow conventional commits and squash merges, you get a clear, user-friendly changelog—it's easy to "skip" commits that don't affect the end user.

I wrote a tool to validate commits, which helps ensure both the git history and changelog look clean: https://github.com/welpo/git-sumi

Here’s my solution: I have a github action that checks if the changelog was touched in the diff. It fails tests if not.

It’s impossible to rewind your brain to the time of when the change is made to consider the total impact to the end user. The best time to write a changelog is when the change happens.

For minor stuff that doesn’t need to be in the changelog, the action checks a label and passes if “skip changelog” is applied. But the default is “hey, you forgot to tell users what they should expect with your change”

I hope I don’t have to work in a project with Conventional Commits.

- The mandatory formatting takes up prime real estate in the subject line

- You don’t get much data out of it: one byte (rounded up) since it’s just “type” and “is breaking change or not”. Not a great trade considering how much it sticks out

- It subjectively looks bad: “feat”, “chore”, codey exclamation mark (punctuation) for breaking changes, and BREAKING CHANGE in all-caps (it’s supposed to be machine readable so why shout, your programs are supposed to pick up this for you)

- You have to care about this for every final commit that lands in the project

- Just to serve a changelog (which is supposed to just ape the git log?)

I'm pretty unclear on what the "bump" command does. Does this create a git tag? Make a new commit? Have hooks to update version constants in the source? Seems like the answer to all of these is "no", and so I'm not really sure how useful it is.

I'm also aware of related tool in this space: semantic-release <https://github.com/semantic-release/semantic-release>. I haven't used it in my repositories, but it seems like a more comprehensive verison of git-cliff.

This looks great! My team does something very similar with a key project but more home-spun because git-cliff either didn't exist or wasn't known about at the time.

For everyone saying "manually written changelogs are so much better" - well, yeah of course! But they also take up a lot more time and resource to curate. I'd hate to see a huge project like gnome or something do this, but I don't think that's the pitch.

As an alternative for either a badly maintained changelog, or no changelog at all, adopting commit or PR conventions is a great idea.

For me, I find this approach better than nothing and would not shame or discourage someone from using it over hand written.

That said, I am wanting a Github action based release workflow and want it to scale to manual edits of changelogs, so this is insufficient for me. Instead, I've been taking notes on changelog fragments as I hope they can offer the best of both worlds, see https://github.com/epage/epage.github.io/issues/23

This may be a task where LLM (AI) could do a reasonable job. Of course the results need to be reviewed by a human.

This is the kind of thing LLMs are great at.

I've been using cocogitto[0] which also generates changelog, also based on Conventional Commits. Plus, it has some nice features such as pre/post-bump hooks.

[0]: https://github.com/cocogitto/cocogitto

I don't think using the verbatim git history as a change log is a good idea.

But if you insist on using the git history for change log, why not use an LLM? You could feed git history to chatgpt and get a nice user-friendly change log.

IMO, changelogs taylored by humans are often better (feel more "whole") than machine generated from commit logs. If anyone wants to see the commit logs, they are there for inspection, and when written well can give a good idea on what has been going on.

I can’t help it, my mind reads this name as a spoonerism:

https://en.wikipedia.org/wiki/Spoonerism

“The GIF search tool that finds it”, perhaps.

I'm not involved with this, but I did create the winget-pkgs issue to get git-cliff available for use on Windows.

Because of this Windows users can simply run "winget install git-cliff".

Small things like this help with adoption.

Just want to say that the animation on the home page is delightful and a lot more creative than you'd expect from a git tool.

maybe I'm basic but I'd rather just use git to do this and not conform to a specific tooling / format

this is a great tool, I dont think it replaces maintaining a proper changelog but it definitely helps track what is added to each release.

I think there should be both a generated changelog and an official changelog when a release is made.

Hah mgmt asked for something like this and boom HN provides!

git-shortlog, which is built in to git, can also write changelogs, with support for arbitrary grouping based on commit metadata.

End user ≠ developer

Git log ≠ ChangeLog

... it's me, Cathy...

Nice tool

Wip Wip Wip ...

Not sure about anything else, but love the animation!