11 ms·

Git-cliff – Generate changelog from the Git history

222 points by orhunp_ 2y ago

amar-laksh 2y ago
Not sure about anything else, but love the animation!
- weinzierl 2y ago
  Then you should check out ratatui.rs (different project, same author) and maybe its presentations on yt for more awesomeness of that kind.
  - dkga 2y ago
    Amazing animation (and idea) indeed, as someone who loves using the terminal and sometimes - only sometimes - like to see something new like this.
Raptor95 2y ago
Nice tool
esafak 2y ago
This is the kind of thing LLMs are great at.
- dewey 2y ago
  That's what I thought when I read the headline but when I checked it looks like it's regex based.
herewulf 2y ago
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.
- Aeolun 2y ago
  I disagree. I find it quite useful to see that a refactor happened in the foobar, when my foobar has suddenly stopped working from one release to the next.
  - j16sdiz 2y ago
    This is quite useful to narrow down the problem when it occur. This is not useful to decide if I should upgrade now, or what should I try out after upgrade --- and this is what a release note should be doing.
- shiroiushi 2y ago
  >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. I disagree: I think it's extremely helpful for users to read dozens or even hundreds of commit messages saying "fixed typo". /s
  - Jochim 2y ago
    This feels like a fairly disingenuous interpretation of how this gets implemented. Normally, commits must match a particular pattern to be included. Those that start with "feat:" might appear in the features section, while those starting with "bug:" show up in fixes. A few simple rules are enough to ensure that an intelligible changelog is generated. Minimal cleanup can then focus on making it presentable. You could even set up your pull request rules to handle this for you. On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates.
    - shiroiushi 2y ago
      This is peak HN: getting accused of being "disingenuous" for making a glib comment complaining about too many "fixed typo" and other trivial commits in a git log. >On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates. Squashing is great IMO, but the problem is that many organizations prohibit it, because it erases a developer's commit history, because apparently it's really, really interesting to pore through dozens of commits where a developer fixed some whitespace, fixed some typos, etc. (Before you say something about rebasing, these same organizations also frequently prohibit that too.)
onion2k 2y ago
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.
- CGamesPlay 2y ago
  > 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'. I disagree. As a technical user who consumes many external repositories, I much prefer reading a changelog to reading a list of commits. First, I'm not reading this in a git client; I'm reading it in a web browser (likely on Github). In this interface, being able to see via headings the changes since my current version and the new version is extremely useful. Second, the change log is distributed with the application, even in cases where the source code isn't (this is especially useful when thinking about things like GUI auto-update checks, where I want to see the change log before I decide to upgrade). Third, the one-line summaries typically link back to commits or PRs, so when I see something I do want more information about, I can easily find the technical discussion about it.
- Jochim 2y ago
  I think it serves a few potential purposes: It provides a solid, accurate draft that can be expanded on when targeting non-technical users. I've often found that lack of visibility leads to messy commits. Surfacing these messages in the changelog introduces an incentive to take more care. With regards to the usefulness of the descriptions, the associated issue is often linked along with the commit message. This is often omitted in hand-written changelogs. In this case the auto-generated changelog acts as an index, allowing the reader to quickly parse what changed and jump to the associated code or ticket.
fphilipe 2y ago
I am definitely more in the changelog-as-a-file camp. From https://keepachangelog.com/ 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.
- pydry 2y ago
  Noise can be excluded.
- airtonix 2y ago
  spent 3 years on a team hoping they would step up a write meaningful changeset titles... however. ended up just getting: - fixed things. - creates new feature x - fixed broken thing. instead of something that's appreciable by non technical people: - when navigating to the nuclear launch code dashboard, a user is no longer mocked for having a likeness to <current unpopular person>. point here is. if your team didn't write good squash merged PR titles before, they won't magically start doing so because you're using changesets.
- nsbk 2y ago
  Me too, but some tools combine the best of both worlds. In my team we use commitizen [1] which drinks both from keepachangelog and conventional commits and we are quite pleased with our changelogs so far. [1] https://commitizen-tools.github.io/commitizen/#features https://commitizen-tools.github.io/commitizen/#features
- WorldMaker 2y ago
  > they're full of noise. Things like merge commits From another angle, merge commits can also be a solution to the problem. `git merge --no-ff --edit` can be a great way to summarize an entire branch of commits. Most PR tools will give you an easy way to create those kind of merge commits. Don't settle for the default "merge branch x into y", create a meaningful title and fill in details/summary of what happened in the branch. With traversal tools like git log --first-parent you can see a high level of just your merge commits with the gnarly details of whatever steps led up to the merge commit itself. I've certainly seen good projects where `git log --first-parent` was always a useful first pass changelog (no matter how "clean" the rest of commits were or were not). Probably still not a changelog you should send as a document to end users (because still written from a development standpoint rather than a user standpoint), but a good place to start writing the end user documentation.
CGamesPlay 2y ago
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 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.
the_duke 2y ago
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/ https://www.conventionalcommits.org/en/v1.0.0/
- wdroz 2y ago
  You can use conventional pre-commit[0] to validate that commit messages follow the convention and use only the types that the team agreed upon. This still requires discipline to choose the "right" type and scope. [0] -- https://github.com/compilerla/conventional-pre-commit https://github.com/compilerla/conventional-pre-commit
- mihaaly 2y ago
  > If you follow this properly There it goes! One more thing to do precisely and not only at dedicated time but continuously on top of all other things to do precisely already inherently around completing a task. Everyone all the time think about the state of changelog communication in addition, and do it well, phrase it for changelog purposes, format it for that as well. While working on changelog on the end will need additional work still. In some simple situation it may have merit though, I admit. Seems like additional trouble (both workload and source of mistakes) in a medium to large team. Except if the developers are well programmed robots themselves, of course, those do not fail (or easy to throw out and replace if they do).
  - lloydatkinson 2y ago
    If a team of devs is incapable of writing good commits with simple prefixes then that's a strong case for adding git hooks that reject commits without the prefix. Before someone starts getting their pants in a twist at this idea, you can configure a solution such that commits to branches don't need a conventional commit format, but that the commit that merges a PR into master must have conventional commit format.
ddulaney 2y ago
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.
- Jochim 2y ago
  I've seen the same thing done within the ticketing system. It's useful when you might want non-developers to contribute to the notes. Being able to dedicate a tag, field, or work item type is pretty handy.
  - weinzierl 2y ago
    We considered generating the changelog from the git commits, the information contained in the PR and from the ticket. Ultimately we also decided to go with the tickets, but I am curious what your reasoning was to go that way?
    - Jochim 2y ago
      Sadly, we didn't end up implementing it ourselves. Release notes were a "nice to have" so it became one of those things that gets kicked down the road. The primary advantage of the ticket-based approach is that it's much easier to involve non-dev stakeholders. I'd choose it whenever other people might want input in the process. Most ticketing systems also offer a lot of flexibility, you could incorporate the ticket name, group tickets by relation, block completion states, act on deployments, etc. The ability to edit the note without rebasing is a major bonus as well. The git-based approach potentially leads to a more readable commit history, and strongly associates any release notes with the actual code change. On the other hand, it's a pain to edit and can distract devs while they're problem solving if not setup well.
      - 2y ago
pavlov 2y ago
I can’t help it, my mind reads this name as a spoonerism: https://en.wikipedia.org/wiki/Spoonerism https://en.wikipedia.org/wiki/Spoonerism “The GIF search tool that finds it”, perhaps.
joshka 2y ago
Here's an example of a changelog that is generated using git-cliff: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md 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/ https://ratatui.rs/highlights/v027/
- weinzierl 2y ago
  The changelog is completely generated with no manual editing afterwords, right? In the same vein, is the highlights doc written by a human?
  - joshka 2y ago
    yes and yes
- keybored 2y ago
  It looks like the commits are lightly processed (scanning “type”, removing it, moving it to the correct section/heading), put in bullet points, adding a hyperlink to the commit hash, using section breaks for something (maybe per PR or something). It looks nice. And verbose. Like a lot of refactoring bullet points. The “squashed” commits don’t look good but that’s the fault of squash commits (as usual). In the end this is a very light shim on top of git log. (Light in terms of data, not light in terms of the discipline and visual overhead the so-called Conventional Commits standard demands).
  - joshka 2y ago
    > It looks like the commits are lightly processed (scanning “type”, removing it, moving it to the correct section/heading), put in bullet points, adding a hyperlink to the commit hash, using section breaks for something (maybe per PR or something). Yeah pretty much. The config is at https://github.com/ratatui-org/ratatui/blob/main/cliff.toml https://github.com/ratatui-org/ratatui/blob/main/cliff.toml > It looks nice. And verbose. Like a lot of refactoring bullet points. Most of the bullet points are single features / changes to the library that are delivered to the users of the library. > The “squashed” commits don’t look good but that’s the fault of squash commits (as usual). Can you give an example of this? Everything you're seeing in the changelog is a commit that has been pushed to the repo with a title message and a manually crafted body - we generally avoid letting the body be the github squash commit PR message junk. > In the end this is a very light shim on top of git log. (Light in terms of data, not light in terms of the discipline and visual overhead the so-called Conventional Commits standard demands). Yeah, and that's generally useful from the perspective that it's available online, searchable in a single doc (which makes it easy to answer questions like "when was blah implemented" There's probably a bunch of things that would make this even better, but there's diminishing returns on the effort involved in doing so.
mattrighetti 2y ago
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 https://github.com/cocogitto/cocogitto
nickcw 2y ago
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/ 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/ 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.
- lloydatkinson 2y ago
  Did you look at the example changelogs git-cliff creates? > 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. Provided the commits use conventional commit format such as "feat(thing): fixed crash when copying file to xyz backend" or "fix(database): generate migrations correctly" not only do you get the type of commit but also the category or area. git-cliff and others then use that to automatically add sections for each category of commit. This wouls surely needing to spend hours on writing changelogs, which seems an insane amount of time to me. > 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.
lloydatkinson 2y ago
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.
kreetx 2y ago
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.
gigatexal 2y ago
Hah mgmt asked for something like this and boom HN provides!
welpo 2y ago
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 https://github.com/welpo/git-sumi
- pseudalopex 2y ago
  Repeated items, items irrelevant to users, details irrelevant to users in each item, and poor organization in each section make the git-sumi release notes unclear and user unfriendly.
  - welpo 2y ago
    You're right; there is a lot of noise in the git-sumi changelog. As it matures (and I tinker less with it), it should get better. Here's a better example on a more mature project: https://github.com/welpo/tabi/blob/main/CHANGELOG.md https://github.com/welpo/tabi/blob/main/CHANGELOG.md
    - pseudalopex 2y ago
      The tabi release notes have items irrelevant to users, details irrelevant to users in each item, and poor organization in each section.
- doix 2y ago
  You don't _need_ to squash, if you don't want too. You can merge and use conventional commits for the merges. Then git log --first-parent gives you the change log whilst also not not forcing you to squash.
epage 2y ago
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 https://github.com/epage/epage.github.io/issues/23
Pawamoy 2y ago
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!
benrutter 2y ago
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.
dkga 2y ago
... it's me, Cathy...
- quesera 2y ago
  I cannot justify upvoting this comment, but I will thank you for bringing a smile to my day.
- lucasoshiro 2y ago
  ... I've come ~
nixpulvis 2y ago
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.
schneems 2y ago
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”
keybored 2y ago
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?)
- jasonpeacock 2y ago
  > You have to care about this for every final commit that lands in the project Same as having a standard coding style, you should have a standard commit message style that you do care about for every commit in the project. A mish-mash of variable quality and variable formatted commits more than subjectively looks bad - it reduces the signal-to-noise of the commit messages. As for the `feat(scope):` in the subject line, it's a very succinct way to communicate the type of the change. Don't make me the read the whole commit to figure out if this was a feature or bug fix, or only affected the build. > Just serve a changelog Sure. But I want the changelog to list features first, then bug fixes, etc. How do I do that automatically with only the git log w/o some sort of standardized tagging of the commits?
  - keybored 2y ago
    > Same as having a standard coding style, you should have a standard commit message style that you do care about for every commit in the project. A mish-mash of variable quality and variable formatted commits more than subjectively looks bad - it reduces the signal-to-noise of the commit messages. I already personally use a standard commit message style.[1] And that standard is about how to structure the prose, not about using any kind of structured markup (outside the trailers section). > As for the `feat(scope):` in the subject line, it's a very succinct way to communicate the type of the change. Don't make me the read the whole commit to figure out if this was a feature or bug fix, or only affected the build. Verbs already serve that purpose most of the time. Then you get redundant lines like `feat: add OAuth 2.0 login`. > Sure. But I want the changelog to list features first, then bug fixes, etc. How do I do that automatically with only the git log w/o some sort of standardized tagging of the commits? If you have such a high volume of commits (that users would care about) that you have have distribute tagging of all commits to all contributors,[2] you can use the trailers section.[3] [1] I don’t expect anyone else to at work. In one free-time project people use the same style, with one exception (against my personal taste). [2] And if you need such a detailed changelog, let alone a fully automatically written one [3] https://news.ycombinator.com/item?id=40820213 https://news.ycombinator.com/item?id=40820213
vzaliva 2y ago
This may be a task where LLM (AI) could do a reasonable job. Of course the results need to be reviewed by a human.
sigmonsays 2y ago
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.
whoomp12342 2y ago
maybe I'm basic but I'd rather just use git to do this and not conform to a specific tooling / format
habosa 2y ago
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.
pheatherlite 2y ago
Wip Wip Wip ...
gradientsrneat 2y ago
git-shortlog, which is built in to git, can also write changelogs, with support for arbitrary grouping based on commit metadata.
egberts1 2y ago
End user ≠ developer Git log ≠ ChangeLog
nerdright 2y ago
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.

222 points by orhunp_ 2y ago

amar-laksh 2y ago

Not sure about anything else, but love the animation!

weinzierl 2y ago
Then you should check out ratatui.rs (different project, same author) and maybe its presentations on yt for more awesomeness of that kind.
- dkga 2y ago
  Amazing animation (and idea) indeed, as someone who loves using the terminal and sometimes - only sometimes - like to see something new like this.

Raptor95 2y ago

Nice tool

esafak 2y ago

This is the kind of thing LLMs are great at.

dewey 2y ago
That's what I thought when I read the headline but when I checked it looks like it's regex based.

herewulf 2y ago

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.

Aeolun 2y ago
I disagree. I find it quite useful to see that a refactor happened in the foobar, when my foobar has suddenly stopped working from one release to the next.
- j16sdiz 2y ago
  This is quite useful to narrow down the problem when it occur. This is not useful to decide if I should upgrade now, or what should I try out after upgrade --- and this is what a release note should be doing.
shiroiushi 2y ago
>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. I disagree: I think it's extremely helpful for users to read dozens or even hundreds of commit messages saying "fixed typo". /s
- Jochim 2y ago
  This feels like a fairly disingenuous interpretation of how this gets implemented. Normally, commits must match a particular pattern to be included. Those that start with "feat:" might appear in the features section, while those starting with "bug:" show up in fixes. A few simple rules are enough to ensure that an intelligible changelog is generated. Minimal cleanup can then focus on making it presentable. You could even set up your pull request rules to handle this for you. On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates.
  - shiroiushi 2y ago
    This is peak HN: getting accused of being "disingenuous" for making a glib comment complaining about too many "fixed typo" and other trivial commits in a git log. >On approval it could look at the linked issue and include the title and appropriate pattern for that issue as the message for any merge/squash commits it creates. Squashing is great IMO, but the problem is that many organizations prohibit it, because it erases a developer's commit history, because apparently it's really, really interesting to pore through dozens of commits where a developer fixed some whitespace, fixed some typos, etc. (Before you say something about rebasing, these same organizations also frequently prohibit that too.)

onion2k 2y ago

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.

CGamesPlay 2y ago
> 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'. I disagree. As a technical user who consumes many external repositories, I much prefer reading a changelog to reading a list of commits. First, I'm not reading this in a git client; I'm reading it in a web browser (likely on Github). In this interface, being able to see via headings the changes since my current version and the new version is extremely useful. Second, the change log is distributed with the application, even in cases where the source code isn't (this is especially useful when thinking about things like GUI auto-update checks, where I want to see the change log before I decide to upgrade). Third, the one-line summaries typically link back to commits or PRs, so when I see something I do want more information about, I can easily find the technical discussion about it.
Jochim 2y ago
I think it serves a few potential purposes: It provides a solid, accurate draft that can be expanded on when targeting non-technical users. I've often found that lack of visibility leads to messy commits. Surfacing these messages in the changelog introduces an incentive to take more care. With regards to the usefulness of the descriptions, the associated issue is often linked along with the commit message. This is often omitted in hand-written changelogs. In this case the auto-generated changelog acts as an index, allowing the reader to quickly parse what changed and jump to the associated code or ticket.

fphilipe 2y ago

I am definitely more in the changelog-as-a-file camp. From https://keepachangelog.com/ 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.

pydry 2y ago
Noise can be excluded.
airtonix 2y ago
spent 3 years on a team hoping they would step up a write meaningful changeset titles... however. ended up just getting: - fixed things. - creates new feature x - fixed broken thing. instead of something that's appreciable by non technical people: - when navigating to the nuclear launch code dashboard, a user is no longer mocked for having a likeness to <current unpopular person>. point here is. if your team didn't write good squash merged PR titles before, they won't magically start doing so because you're using changesets.
nsbk 2y ago
Me too, but some tools combine the best of both worlds. In my team we use commitizen [1] which drinks both from keepachangelog and conventional commits and we are quite pleased with our changelogs so far. [1] https://commitizen-tools.github.io/commitizen/#features https://commitizen-tools.github.io/commitizen/#features
WorldMaker 2y ago
> they're full of noise. Things like merge commits From another angle, merge commits can also be a solution to the problem. `git merge --no-ff --edit` can be a great way to summarize an entire branch of commits. Most PR tools will give you an easy way to create those kind of merge commits. Don't settle for the default "merge branch x into y", create a meaningful title and fill in details/summary of what happened in the branch. With traversal tools like git log --first-parent you can see a high level of just your merge commits with the gnarly details of whatever steps led up to the merge commit itself. I've certainly seen good projects where `git log --first-parent` was always a useful first pass changelog (no matter how "clean" the rest of commits were or were not). Probably still not a changelog you should send as a document to end users (because still written from a development standpoint rather than a user standpoint), but a good place to start writing the end user documentation.

CGamesPlay 2y ago

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 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.

the_duke 2y ago

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/ https://www.conventionalcommits.org/en/v1.0.0/

wdroz 2y ago
You can use conventional pre-commit[0] to validate that commit messages follow the convention and use only the types that the team agreed upon. This still requires discipline to choose the "right" type and scope. [0] -- https://github.com/compilerla/conventional-pre-commit https://github.com/compilerla/conventional-pre-commit
mihaaly 2y ago
> If you follow this properly There it goes! One more thing to do precisely and not only at dedicated time but continuously on top of all other things to do precisely already inherently around completing a task. Everyone all the time think about the state of changelog communication in addition, and do it well, phrase it for changelog purposes, format it for that as well. While working on changelog on the end will need additional work still. In some simple situation it may have merit though, I admit. Seems like additional trouble (both workload and source of mistakes) in a medium to large team. Except if the developers are well programmed robots themselves, of course, those do not fail (or easy to throw out and replace if they do).
- lloydatkinson 2y ago
  If a team of devs is incapable of writing good commits with simple prefixes then that's a strong case for adding git hooks that reject commits without the prefix. Before someone starts getting their pants in a twist at this idea, you can configure a solution such that commits to branches don't need a conventional commit format, but that the commit that merges a PR into master must have conventional commit format.

ddulaney 2y ago

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.

Jochim 2y ago
I've seen the same thing done within the ticketing system. It's useful when you might want non-developers to contribute to the notes. Being able to dedicate a tag, field, or work item type is pretty handy.
- weinzierl 2y ago
  We considered generating the changelog from the git commits, the information contained in the PR and from the ticket. Ultimately we also decided to go with the tickets, but I am curious what your reasoning was to go that way?
  - Jochim 2y ago
    Sadly, we didn't end up implementing it ourselves. Release notes were a "nice to have" so it became one of those things that gets kicked down the road. The primary advantage of the ticket-based approach is that it's much easier to involve non-dev stakeholders. I'd choose it whenever other people might want input in the process. Most ticketing systems also offer a lot of flexibility, you could incorporate the ticket name, group tickets by relation, block completion states, act on deployments, etc. The ability to edit the note without rebasing is a major bonus as well. The git-based approach potentially leads to a more readable commit history, and strongly associates any release notes with the actual code change. On the other hand, it's a pain to edit and can distract devs while they're problem solving if not setup well.
    - 2y ago

pavlov 2y ago

I can’t help it, my mind reads this name as a spoonerism: https://en.wikipedia.org/wiki/Spoonerism https://en.wikipedia.org/wiki/Spoonerism “The GIF search tool that finds it”, perhaps.

joshka 2y ago

Here's an example of a changelog that is generated using git-cliff: https://github.com/ratatui-org/ratatui/blob/main/CHANGELOG.md 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/ https://ratatui.rs/highlights/v027/

weinzierl 2y ago
The changelog is completely generated with no manual editing afterwords, right? In the same vein, is the highlights doc written by a human?
- joshka 2y ago
  yes and yes
keybored 2y ago
It looks like the commits are lightly processed (scanning “type”, removing it, moving it to the correct section/heading), put in bullet points, adding a hyperlink to the commit hash, using section breaks for something (maybe per PR or something). It looks nice. And verbose. Like a lot of refactoring bullet points. The “squashed” commits don’t look good but that’s the fault of squash commits (as usual). In the end this is a very light shim on top of git log. (Light in terms of data, not light in terms of the discipline and visual overhead the so-called Conventional Commits standard demands).
- joshka 2y ago
  > It looks like the commits are lightly processed (scanning “type”, removing it, moving it to the correct section/heading), put in bullet points, adding a hyperlink to the commit hash, using section breaks for something (maybe per PR or something). Yeah pretty much. The config is at https://github.com/ratatui-org/ratatui/blob/main/cliff.toml https://github.com/ratatui-org/ratatui/blob/main/cliff.toml > It looks nice. And verbose. Like a lot of refactoring bullet points. Most of the bullet points are single features / changes to the library that are delivered to the users of the library. > The “squashed” commits don’t look good but that’s the fault of squash commits (as usual). Can you give an example of this? Everything you're seeing in the changelog is a commit that has been pushed to the repo with a title message and a manually crafted body - we generally avoid letting the body be the github squash commit PR message junk. > In the end this is a very light shim on top of git log. (Light in terms of data, not light in terms of the discipline and visual overhead the so-called Conventional Commits standard demands). Yeah, and that's generally useful from the perspective that it's available online, searchable in a single doc (which makes it easy to answer questions like "when was blah implemented" There's probably a bunch of things that would make this even better, but there's diminishing returns on the effort involved in doing so.

mattrighetti 2y ago

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 https://github.com/cocogitto/cocogitto

nickcw 2y ago

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/ 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/ 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.

lloydatkinson 2y ago
Did you look at the example changelogs git-cliff creates? > 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. Provided the commits use conventional commit format such as "feat(thing): fixed crash when copying file to xyz backend" or "fix(database): generate migrations correctly" not only do you get the type of commit but also the category or area. git-cliff and others then use that to automatically add sections for each category of commit. This wouls surely needing to spend hours on writing changelogs, which seems an insane amount of time to me. > 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.

lloydatkinson 2y ago

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.

kreetx 2y ago

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.

gigatexal 2y ago

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

welpo 2y ago

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 https://github.com/welpo/git-sumi

pseudalopex 2y ago
Repeated items, items irrelevant to users, details irrelevant to users in each item, and poor organization in each section make the git-sumi release notes unclear and user unfriendly.
- welpo 2y ago
  You're right; there is a lot of noise in the git-sumi changelog. As it matures (and I tinker less with it), it should get better. Here's a better example on a more mature project: https://github.com/welpo/tabi/blob/main/CHANGELOG.md https://github.com/welpo/tabi/blob/main/CHANGELOG.md
  - pseudalopex 2y ago
    The tabi release notes have items irrelevant to users, details irrelevant to users in each item, and poor organization in each section.
doix 2y ago
You don't _need_ to squash, if you don't want too. You can merge and use conventional commits for the merges. Then git log --first-parent gives you the change log whilst also not not forcing you to squash.

epage 2y ago

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 https://github.com/epage/epage.github.io/issues/23

Pawamoy 2y ago

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!

benrutter 2y ago

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.

dkga 2y ago

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

quesera 2y ago
I cannot justify upvoting this comment, but I will thank you for bringing a smile to my day.
lucasoshiro 2y ago
... I've come ~

nixpulvis 2y ago

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.

schneems 2y ago

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”

keybored 2y ago

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?)

jasonpeacock 2y ago
> You have to care about this for every final commit that lands in the project Same as having a standard coding style, you should have a standard commit message style that you do care about for every commit in the project. A mish-mash of variable quality and variable formatted commits more than subjectively looks bad - it reduces the signal-to-noise of the commit messages. As for the `feat(scope):` in the subject line, it's a very succinct way to communicate the type of the change. Don't make me the read the whole commit to figure out if this was a feature or bug fix, or only affected the build. > Just serve a changelog Sure. But I want the changelog to list features first, then bug fixes, etc. How do I do that automatically with only the git log w/o some sort of standardized tagging of the commits?
- keybored 2y ago
  > Same as having a standard coding style, you should have a standard commit message style that you do care about for every commit in the project. A mish-mash of variable quality and variable formatted commits more than subjectively looks bad - it reduces the signal-to-noise of the commit messages. I already personally use a standard commit message style.[1] And that standard is about how to structure the prose, not about using any kind of structured markup (outside the trailers section). > As for the `feat(scope):` in the subject line, it's a very succinct way to communicate the type of the change. Don't make me the read the whole commit to figure out if this was a feature or bug fix, or only affected the build. Verbs already serve that purpose most of the time. Then you get redundant lines like `feat: add OAuth 2.0 login`. > Sure. But I want the changelog to list features first, then bug fixes, etc. How do I do that automatically with only the git log w/o some sort of standardized tagging of the commits? If you have such a high volume of commits (that users would care about) that you have have distribute tagging of all commits to all contributors,[2] you can use the trailers section.[3] [1] I don’t expect anyone else to at work. In one free-time project people use the same style, with one exception (against my personal taste). [2] And if you need such a detailed changelog, let alone a fully automatically written one [3] https://news.ycombinator.com/item?id=40820213 https://news.ycombinator.com/item?id=40820213

vzaliva 2y ago

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

sigmonsays 2y ago

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.

whoomp12342 2y ago

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

habosa 2y ago

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.

pheatherlite 2y ago

Wip Wip Wip ...

gradientsrneat 2y ago

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

egberts1 2y ago

End user ≠ developer Git log ≠ ChangeLog

nerdright 2y ago

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.