Git-cliff – Generate changelog from the Git history

222 点作者 orhunp_11 个月前

32 条评论

nickcw11 个月前

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`.<a href="https://rclone.org/changelog/" rel="nofollow">https://rclone.org/changelog/</a>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 <a href="https://www.conventionalcommits.org/en/v1.0.0/" rel="nofollow">https://www.conventionalcommits.org/en/v1.0.0/</a> 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.

评论 #40821750 未加载

评论 #40822637 未加载

评论 #40819255 未加载

评论 #40821610 未加载

评论 #40821572 未加载

评论 #40821974 未加载

fphilipe11 个月前

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

评论 #40822763 未加载

评论 #40819034 未加载

评论 #40818632 未加载

评论 #40818807 未加载

joshka11 个月前

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

评论 #40821868 未加载

评论 #40818944 未加载

评论 #40827323 未加载

herewulf11 个月前

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.

评论 #40818600 未加载

评论 #40818392 未加载

评论 #40818522 未加载

Pawamoy11 个月前

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!

onion2k11 个月前

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.

评论 #40818290 未加载

评论 #40819285 未加载

评论 #40818729 未加载

评论 #40820272 未加载

the_duke11 个月前

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] <a href="https://www.conventionalcommits.org/en/v1.0.0/" rel="nofollow">https://www.conventionalcommits.org/en/v1.0.0/</a>

评论 #40819136 未加载

评论 #40818680 未加载

评论 #40820487 未加载

ddulaney11 个月前

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.

评论 #40818787 未加载

评论 #40822725 未加载

nixpulvis11 个月前

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.

welpo11 个月前

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

评论 #40828205 未加载

评论 #40822777 未加载

schneems11 个月前

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”

keybored11 个月前

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

评论 #40821820 未加载

CGamesPlay11 个月前

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 <<a href="https://github.com/semantic-release/semantic-release">https://github.com/semantic-release/semantic-release</a>>. I haven't used it in my repositories, but it seems like a more comprehensive verison of git-cliff.

benrutter11 个月前

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.

epage11 个月前

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

vzaliva11 个月前

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

esafak11 个月前

This is the kind of thing LLMs are great at.

评论 #40822389 未加载

mattrighetti11 个月前

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]: <a href="https://github.com/cocogitto/cocogitto">https://github.com/cocogitto/cocogitto</a>

nerdright11 个月前

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.

kreetx11 个月前

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.

pavlov11 个月前

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

lloydatkinson11 个月前

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.

habosa11 个月前

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.

whoomp1234211 个月前

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

sigmonsays11 个月前

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.

gigatexal11 个月前

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

gradientsrneat11 个月前

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

egberts111 个月前

End user ≠ developerGit log ≠ ChangeLog

dkga11 个月前

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

评论 #40820684 未加载

评论 #40824270 未加载

Raptor9511 个月前

Nice tool

pheatherlite11 个月前

Wip Wip Wip ...

amar-laksh11 个月前

Not sure about anything else, but love the animation!

评论 #40818804 未加载