I've worked with 5 different SCMs and I'm convinced that the reason why git repos often have such poor commit messages is because of the git commit style guide. So much of it only makes sense once you realize it's been optimized for like 5 of its original users reading it on 72 character terminal screens.
Asking people to fit a meaningful description of the change into 50 characters is silly, and it's IMO the reason why so many of them just write "fix bug" and call it a day.
This is, I believe, still the best guide out there. When I'm coaching juniors, I recommend this guide, over the opinionated and outdated git "best practices" and I think the results are much better.
That Google guide also says that the first line of the commit message should be a "short summary of what is being done". Is your complaint that 50/72 characters is too short? How long can it be before no longer meets the Google criteria, in your opinion?
Yeah, I specifically think 50 is too short. I am a big fan of brevity, but I think the sweet spot is somewhere around 100. Consider that all of these messages exceed the 50-character limit:
[startup] Don't drop uid until all controller fds are open
[bpf] Fix the exec exchange hitting verifier limit on Fedora
[controller] Optimize partial policy updates with delta
They're as short (IMO) as can be without omitting useful information, but git says they're all illegal by some margin.
I agree on the value of concise writing and dislike word salads, but if you're a junior engineer, then I have maybe 1 hour with you per week and I probably shouldn't spend that time being your English teacher.
I know I've seen some people recommend 50 (my guess is that's to make some room for metadata from commands like `git log --online` in an 80-column terminal?) but I've personally always capped all lines at 72, including the first. 100 seems like a reasonable limit too, but I probably wouldn't go above that.
> git says they're all illegal by some margin
Git will accept almost anything as a commit message. Is there a specific style guide you're referring to?
---
EDIT: Huh, I guess git does have an official recommendation. I'd never noticed this text in `git help commit`:
> Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description.
I wouldn't feel bad about not following this advice. Even the author doesn't seem dogmatic about it.
> if you're a junior engineer, then I have maybe 1 hour with you per week and I probably shouldn't spend that time being your English teacher
It's not important enough to make a big deal out of, but if I see it over and over from the same person I might mention it during code review ("your commit messages are a bit wordy; for example instead of '…', consider '…'") or write down as part of a style guide (e.g. if we're tagging commits like in your examples, wherever we wrote down the rules for that). It's the same for other unimportant things that it's nice to agree on (e.g. capitalization of initialisms in code—is it `.toJson()` or `.toJSON()`?).
I may be misunderstanding: are you saying a commit message with a 200-character-long first line could be an example of a "good" message to you/Googlers? To me that seems like something that could almost certainly be summarized further, regardless of how complex the changeset is (if not it's a sign the commit should be broken up into multiple simpler commits).
Can you give me an example of a commit where the "short, focused summary" can only be usefully-expressed in 200+ characters?
A good dev isnt necessarily a good writer. Summarising complexity concisely is difficult.
Restrictions lead devs to write to useless messages like 'fixed a bug' rather than messages that are slightly verbose but actually useful.
Most messages wont be 200 chars. But id rather 200 chars of useful text than 72chars of useless text.
The real world is full of average devs that are average writers under time pressure to deliver code. Expecting them to deliver above average commit messages like googles examples is a pipe dream.
Should this reasoning be applied to other skills involved in software engineering? If someone never writes tests, or over-architects everything, or has terrible people skills, or never updates documentation, or doesn't bring attention to blockers, or constantly forgets to update the issue tracker, or doesn't follow the local code conventions, or works on random tasks and ignores high-priority ones, etc etc etc the solution isn't usually "don't ask them to do a thing they're bad at", it's "help them get better".
The important question is whether "skimmable commit messages" is a thing you care about enough to advocate for and teach people about. Maybe you don't, and that's fine.
> But id rather 200 chars of useful text than 72chars of useless text.
I completely agree with this. I just don't think those are the only two options.
> Expecting them to deliver above average commit messages like googles examples is a pipe dream.
This thread started with praise for that Google guide and I assumed you were of similar opinion given your reply. That's why I kept referring to it.
1. I basically agree with everything you say, I only think the limit should be ~50-100% higher. Not 10x, but 1.5-2x.
2. For some reason, concise writing is the hardest thing to teach and demand consistently. I think a part of is that people try to hide incompetence behind a word salad, but also I think non-native speakers use more words than they need. It gets to a point where you either have to become everyone's English teacher or accept some amount of word salad.
It probably depends on the codebase, but I find the best motivation for writing solid commit messages is reading commit messages. Tools like gitlens make this really easy.
Almost daily, I use commit messages and history as part of understanding why a decision was made, why a seemingly obvious alternative wasn’t chosen, etc. seeing the commit title on every line, and hovering to see the full message has become a core editor feature for me.
It’s kind of like testing, the more I do it, the more I want to do it because the value is so consistently reinforced.
There’s nothing like being able to track down exactly why a decision was made 6 years ago in a part of the code base you are struggling to understand written by someone who left before you joined the team.
10,000% this. Attaching JIRA tickets, etc. to the commit helps for searching as well. I've worked with a number of people who do not believe in this and it drives me insane ; I try to enforce it, but there's a lot of messages like "fixed bug" that have zero context or detail associated with them.
I don't understand why so many engineers are like this.
Attaching JIRA issues makes a ton of sense for features that are described in JIRA. If we're talking about a bug that was found by a developer, unmotivated by a ticket, it would generally make more sense to just describe the bug directly in the commit message. This is of course not true if the JIRA tickets are used for something else downstream, like informing users of fixed bugs, or tracking changes.
The other issue with tagging JIRA tickets is that junior developers will believe that to be enough (you can just read the ticket) and wont understand why they need to describe the change from a technical angle, when it's already described in JIRA.
Commit messages are immutable. Linking them to a bug ticket gives you a mutable place to record any new information about the bug that you discover in the future. (For example, that it affected more cases than you originally thought, or that the fix caused another bug.) This new information will be discoverable when starting from the original commit (found e.g. by doing a blame on a particular line of source).
To fail to do so is a gigantic missed opportunity in my opinion. You never know when you will need it.
Attaching ticket numbers has always been enforced by automated checks wherever I have worked, so it is not necessary to “try” to enforce it.
Similarly with AI it is fairly simple to have eg a pre-merge check that validates the commit msg is somewhat useful. This could be implemented for example with GitHub org level checks that must run in a PR.
YOU should be writing your commit messages, not an AI.
You can always generate a new commit message (or summary, alternative summary, etc) down the road with AI. You can never replace your mind being in the thick of a changeset.
The author of the commit doesn't matter per se. If someone is just having AI summarize their changes and using that as the commit message, I agree that they're doing it wrong.
These days, lots of my commit messages are drafted by AI after having chatted at length about the requirements. If the commit message is wrong or incomplete, I'll revise it by hand or maybe guide the AI in the right direction. That tends to be a much more useful and comprehensive description of the commit's intent than what I would naturally find worthwhile to write on my own.
OP's approach is interesting as well, at least in principle, and if it works well it might be the next best option in the absence of a chat log. It should just make sure to focus on extracting the "why" more than describing the "what".
> than what I would naturally find worthwhile to write on my own.
I take issue with that statement. There's nothing "natural" about documentation. You're not "naturally disposed" to writing a certain level of documentation. It's a skill and a discipline. If you don't think it's worthwhile to write documentation, that's not a "natural failing". You're making a judgment, and any missing documentation is an error in judgment.
I meant "natural" in a context of having more urgent immediate priorities than extensively detailed documentation at the commit level — not an error in judgement, just a tradeoff.
If a given project has time/budget to prioritize consistent rigorous documentation, of course it should consider doing so. AI's ability to reduce the cost of doing so is a good thing.
If we assume, as many do, that we are going to delegate the work of "understanding the code" to AI in the coming years, this surely becomes even more important.
AI writing code and commit messages becomes a loop divorced from human reasoning. Future AIs will need to read the commit history to understand the evolution of the code, and if they're reading poor summaries from other AIs it's just polluting the context window.
Commit messages are documentation for humans and machines.
Writing commit messages is one of these mundane chores I’d gladly delegate to LLMs which are very very good at this kind of thing.
I mean, if you really know you code, you know it, there is no much value in reinforcing it in your head one more time via writing comprehensive commit messages - it’s a waste of time, imho.
Hard disagree, though it’s probably dependent on your domain and/or how expressive your test suite is.
But even if that were true, reading a two liner explanation is very obviously more time efficient than reviewing a whole commit diff.
Super common case: you got a subtle bug causing unexpected values in data. You know from the db or logs that it started on 2025-03-02. You check the deployment(s)of that day and there are ~20 of them.
You can quickly read 20 lines in the log and have a good guess of which is likely to be related or go for a round of re-reviewing 20 multi file pull requests and reverse engineer the context from code.
"Super common case" is "initial commit", "fix spelling in README.md", or "small refactor". If your "super common case" is "subtle bug causing unexpected values in data" then you are doing something very, very wrong.
Perhaps this is about commit granularity. If keeping the history about advancing the task is not useful, then I’d merge these commits together before merging the PR; in some workflows this is set up to happen automatically too.
I agree in principle, but in practice, it's horrible right now.
Most AI generate commit messages and PR descriptions are much too verbose and contain 0 additional informational value that couldn't be parsed from the code directly. Most of the time I'd rather read 2 sentences written by a human than a wall of text with redundant information.
Sounds like you haven't been working long enough to forget your decisions, which you WILL do eventually. In such cases, where you're looking at code you wrote 10 years ago and you find a weird line, when you view the git blame and read the commit message, you'll be very thankful that you explain not just "what" you did, but "why" you did this, something an AI will have a very hard time doing.
You don't have to if you don't want to, but if you think "this commit message is just a summary of the changes made", you'll never write a useful commit message.
I’ve been working in the industry for two decades, and I think commit messages is not the best place for storing decisions and associated context. I personally prefer ADRs.
Two decades and you don't see any value in writing down what's currently in your head?
Anyhow, ADRs are good, but they stand for Architectural decisions, not every decision is at that level.
In general, if there's a better place to store explanations, do use it, but often, in many projects, commit messages are the least bad place; and it's enormously better to write there than nowhere at all.
> I mean, if you really know you code, you know it, there is no much value in reinforcing it in your head one more time via writing comprehensive commit messages - it’s a waste of time, imho.
I know the code...when I write it. But 2 weeks later all the context is gone, and that's just _for me_. For my colleagues who also have to be in that code, they don't even start with context.
I mean do what works for you, but understand the bulk of the work that this applies to is for >1 person shops with code bases too big to fit in ones head at all, much less for more than a day or so.
This reminds me of the time when I put extra effort to write good commit messages, explain 'the theory'[1] behind when it makes sense, name Chesterton's fences and generally provide guidance to the future engineer who has to look through this to understand why something was done in a certain way.
This was a delayed project running out of budget and everything had to be completed within a few months. However, the management in it's infinite wisdom also did a complete source code/issue management platform change.
The person who did the repo migration went with the default settings. (I believe this was the case. I forget the details. I would also only half blame the person because everything was rushed)
Everything up to that point was committed with "Made by so and so bot".
This was way ahead of Google was allegedly committing "well over 30%" of code by AI. I witnessed the true pioneers in this space.
A lot of developers are afraid of referring to themselves in a commit message. I think this is a mistake. Treat a commit like an email accompanying a patch. Explain to the reader (probably you, five years from now!) why you’re making the changes you are in a conversational, but technical tone.
This is just a complete braindead commit. Without looking at the code I could probably take 5 minutes to make sense of the commit message, being intrigued something interesting or important is happening. The message is massively over the top, it has way more text then actual code changes. It wastes time.
I am not against AI as a helper in various places. But if possible it should be an opt-in tool if deemed useful. If someone wants to get a summary about a non trivial commit, that can be useful. Even better if the committer writes about the intentions and reasons for the commit, so an AI could match those with the actual code. Don't reiterate whats happening in a patch. Give the meta that isn't there or less obvious. Please.
You see the same with code and text generated by LLMs. Overly verbose, comments that repeat code, and commit messages that repeat what is done in code, but not WHY.
> The full path specification in `go build` was redundant given the context of how Go modules are structured. Simplifying the instructions improves clarity and reduces confusion for new users or contributors.
The explanation doesn't seem quite right. The module mentioned in that command was moved to the project root, in such a way that the command no longer needs to specify a path. So the full path specification wasn't redundant; the updated version of it, became redundant.
And all of this was done in a single commit. Better (disclaimer, I have no experience using Go. Actual Go developers probably don't even need to be told this much):
Use github.com/arpxspace/smartcommit namespace
`go.mod` is updated with an explicit package namespace, and import
statements adjusted to match.
and then:
Rename main module
`cmd/smartcommit.go` is moved to `main.go`, and the README adjusted to
match. (Using this name allows omitting the main module path from the
build command.)
and then:
Simplify prose in README.md
(No explanation required for the last one.)
There's no need to justify that your changes are "in accordance with best practices", tell a story about "ongoing efforts" (unless you actually have other recent commits that you want to group together like that conceptually), etc. Commit messages are for other developers. Another developer who reads, in effect, "this change was made in the hopes that YOU will have an easier time contributing to the project"... is going to feel patronized.
But making fine-grained commits with short messages will help in the long run. No amount of prose in commit messages can actually organize the commits. Meanwhile, the AI's summary completely ignored a change I would recommend splitting out into a separate (third) commit.
> There's no need to justify that your changes are "in accordance with best practices", tell a story about "ongoing efforts" (unless you actually have other recent commits that you want to group together like that conceptually), etc.
LLMs are very prone to generalisation and marketing language like this. Despite being sycophants, they are also trained to speak as if they constantly have to justify and persuade.
This is called out in the Wikipedia meta I linked to in another comment. They're great red flags to look out for in any writing; humans, myself included, often used this kind of lazy construction!
If I needed this LLM output, which I probably don't, but let's say I do, I can just generate this myself. It's disrespectful to others to generate LLM output for them. Just send them the prompt. We all have access to these tools. It's like sending someone a pre-masticated apple. I have my own teeth, thank you.
What you failed to realise is that the 'prompt' has been sent to you - only indirectly, as the project is fully open source. Just look at the source code.
The prompt from that project will be even more worthless, it's just a generic instruction to create a generic summary. It's about having human feedback in commit messages. What are their reasons, problems, intentions for the patch.
Thanks for sharing this! This kind of quick and easy grasp one pagers is how this type of things should be done. We should drum it up loud whenever we can.
I have a coworker that makes every branch into a story about wizards, elfs, or whatever. There's a whole arc that explains the story of the commit in a fun way. I have no idea how he comes up with it all for the past 10 years.
I find that the CC structure helps me scan a list of recent commits, e.g. when squashing something into a past commit or trying to find where to navigate.
I don't spend a lot of time on trying to come up with scopes etc, I just make sure that my commit does one thing that fits the label.
I'm surprised to read that someone not only finds no value in conventional commits, but actively hates it. Wow.
A few reasons to care about CCs:
- The first few characters of a commit message tell you immediately the type of change you should expect. This tells you part of the "what" at a glance. If you're looking for a bug fix, for example, you can safely ignore any other type of commit.
- Thinking about the type of change you're committing helps you create atomic commits. Anything that is not strictly related should go in a separate commit. Hopefully you already know why you should care about this.
- A conventional commit message also often includes the change scope. This is a handy way to indicate the subsystem that was changed, which is also useful for filtering, searching, aggregating, etc.
- They help with writing change logs. I'm a strong proponent of the idea that change logs shouldn't be just autogenerated dumps of commit messages, but carefully redacted for the intended audience, and CCs can help with grouping changes by type or scope. These days LLMs do a decent job at generating this type of changelog (even though it should still be manually reviewed and tweaked), and the additional metadata provided by CCs helps them make it more accurate.
> The first few characters of a commit message tell you immediately the type of change you should expect.
1. Why do I care about this particular classification of "type" of change?
2. "The first few characters" of the message aren't actually what I necessarily see first, anyway.
> If you're looking for a bug fix, for example, you can safely ignore any other type of commit.
1. If I'm looking for a bug fix, I'm using tools like git blame and git bisect.
2. How often do bugs actually get fixed by a single commit, that has that bug fix as their sole purpose, and which is recognized as a bug fix at the time of writing? I'm guessing it's much lower than one would naively expect.
3. If I'm looking for a bug fix, I'm looking for the fix for a specific bug, which is probably most recognizable by some bug tracker issue ID. (And if not, it's most searchable that by figuring out an ID and looking that up). So I'm scanning lines for a # symbol and a number, which I would definitely not expect to be at the start of the line.
> Thinking about the type of change you're committing helps you create atomic commits. Anything that is not strictly related should go in a separate commit. Hopefully you already know why you should care about this.
Yes. And I do this by thinking about a verb that naturally belongs at the beginning of the sentence (fragment) describing the commit. "Bugfix", "feature", and "enhancement" aren't actions.
The discipline of organizing commits is orthogonal to the discipline of labeling them.
> A conventional commit message also often includes the change scope.
One that is thoughtfully written by hand will naturally include the scope of the change any time that this concept is meaningful.
What I don't understand is why you would object to having more metadata attached to your commits. That is essentially what CCs are: additional metadata. Just like the author, date, Co-authored-by, Signed-off-by, and other trailers. It is information that can help you use your Git history in different ways.
You may find no use for this information, or find that it clutters the subject line, but I've addressed both arguments in my previous replies, and won't repeat it here.
> If I'm looking for a bug fix [...]
I mentioned a bug fix as an example, so I'm not sure why you're so focused on that.
CCs introduce a convention to how type and scope are specified. You're not required to use any of the proposed types, and should certainly come up with scopes that make sense for your code base. How you use that information is up to you, and I mentioned several ways that I've personally found it useful.
> The discipline of organizing commits is orthogonal to the discipline of labeling them.
I don't follow. You organize things by grouping them according to some criteria, and labels are required to uniquely identify those groups.
> One that is thoughtfully written by hand will naturally include the scope of the change any time that this concept is meaningful.
Ehm, sure, but CCs provide a framework that standardizes the way information is presented in a well structured repository. A scope is something most repos already use; i.e. it's common to see `<scope>: ...` in repos that don't follow CCs. Attaching a type of commit is another bit of information that further groups commits, and the notation `<type>(<scope>): ...` is just the suggested convention. Which, BTW, naturally came from the way some projects were already structuring their commits.
> I mentioned a bug fix as an example, so I'm not sure why you're so focused on that.
Did you consider it was an example in their comment as well? Fewer features than bug fixes are single commits for example.
> You're not required to use any of the proposed types
> the notation `<type>(<scope>): ...` is just the suggested convention
Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.
The type feat MUST be used when a commit adds a new feature to your application or library.
The type fix MUST be used when a commit represents a bug fix for your application.
A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., fix(parser):[1]
Ha. That's just the language of the RFC specification. This is not some protocol you MUST support exactly as described. It's an attempt at standardizing a convention, and such language makes it easier to follow.
Regardless, blindly following any proposed software development convention or practice is rarely a good idea. It's smarter to get informed, pick and choose practices that make sense to you, and adapt them to your specific workflow.
If you don't find what the Conventional Commits specification proposes valuable, that's fine, but my argument is that it's shortsighted and a mistake. Cheers!
> why you would object to having more metadata attached to your commits
It gets in the way because it takes pride position at the start of the commit message. If you want to put it at the end that might be less annoying but I've never seen anyone do that.
I think the main point is that I almost never arrive at a commit by exhaustively reading through a list of commit messages. It's almost always through some other kind of link like git blame or a GitHub issue/PR.
It's also just really low value information. Imagine if every commit message started with how many lines of code it changed. That would be pretty annoying right?
It's pretty handy when tools like lazy.nvim display changes as a list of commit summaries and you have to make a fast value judgment on if you should allow the upgrade.
Outside of that, I agree that it's silly to put it in the summary and seems to be a symptom of people writing crap commit messages.
If all you ever write or look at is the summary then obviously it needs to go in there or it'll never be seen.
Eh, I wouldn't say it's a waste of bytes. Conventional Commits are useful for many scenarios.
This metadata could also be added via trailers, but most Git UIs don't show them prominently, or at all. So prefixing the subject is still the way to go.
I’d rather not hack my process around the deficiencies of someone else’s poor UI choices. As long as the data is stored in a powerful, structured format, you can serve that up in any way that’s sensible to you with `git log` and other shell friends.
That's your prerogative, but a) conventions are not "hacks", and b) the main benefit of CCs are their visibility. If most code forge web UIs and standalone tools don't make this information visible, it's not of much use. `git log` is just one way to surface this information, and "shell friends" can also make "poor UI choices".
I don't find commit messages useful for historical reasons (git log), I squash them anyway when merging PR. Commit messages are very helpful to a reviewer to get a necessary context and intent behind the change. Without it, I need to figure out it my self when reviewing.
It is very easy to get a habit of committing often and in AI era i don't write commits anymore. So there is no excuse.
The 2% of cases when you need the commit log (or more importantly: someone else who inherits your code...) justifies writing good messages imho.
If you make a change to your codebase, normally you know what you want to achieve and why (otherwise... what are you even doing?). A commit message is just putting that in writing... that only takes a few seconds, often less than it takes to write the code.
So it's just a good habit to have. It forces you to think more about the changes you do & why, so it makes you a better software developer. Creating any new habit always takes some energy initially, but it's worth it.
This will lead to engineers and tech people with less and less communicative skills... Being able to summarise your work and build solid descriptions about the main points of the commit is something so basic that should not be lost... If english is not your main language or you are not that good at writing, I understand that you could make a draft and ask AI to improve it or rewrite it, but this tool is directly a black box that builds the entire commit message based on a couple of prompts, as if it was an impossible task to be done by a human.
Alternative: I do a lot of commits just marked "wip" as I go, then when I'm ready to consider a PR, I rebase my branch into something for public consumption. Some commits will get thoughtful messages when warranted, others will get one line, and the PR description will tie it all together with screenshots and links to the most interesting parts.
(On a good day, that is. Though even on a bad day I don't let "wip" commits into the main branch.)
I'd look to Peter Naur's 1985 paper, "Programming as Theory Building," to remind us that writing meaningful commit messages is essential insofar as it is the discipline that confirms and preserves the intellectual "theory" of our work, distinguishing it from mere text production. In Naur's view, programming is fundamentally the activity of builsing theory, which he defines as the knowledge a person must possess not only to intelligently perform tasks, but also to explain them, to answer queries about them, to argue about them, and so forth. The source code is merely an artifact, and neither machine code nor source code contains the wisdom of knowing how the program works, or more critically, why the program was written the way it was instead of some other way that would have accomplished the same task.
The act of composing a descriptive and concise commit message compels the programmer to transition from the task of "path-making" (writing code) to the intellectual work of explaining the process, which is necessary to grok the change completely.
Reviving the theory of an existing program is a difficult, cult-frustrating, and time-consuming effort. When theory-building is neglected, we lose the intellectual foundation that dictates the program's purpose and design, trapping future maintenance efforts in a costly, confusing cycle of trying to deduce intent from artifact alone
Meaningful commit messages are meant to be read later and be useful. I'm not going to read through 8 sentences of generated slop, would rather look through the diff.
I'm assuming the commits in the repo were generated with the tool itself. In that case, commit `cc677f7` has a (in my opinion) terrible commit message. It starts out with a listing of stuff I could just as well read from the patch. It then contains another list that tries to explain the why, but it ends up being useless fluff like `The full path specification in `go build` was redundant given the context of how Go modules are structured.` and `streamlining the project structure and reducing unnecessary directory complexity.` which tells me exactly nothing about why those changes were made.
It generates a whole lot of text that makes me none the wiser as to why you wanted to do any of those changes. It feels like a robot trying to justify the changes post hoc. Which it of course is, so that's understandable.
Don't take this comment as rudeness BTW. It's cool that you're making a fun little tool. I'm assuming you care about writing more useful commit messages, so I thought I'd give you some feedback on that part.
Yeah totally see where you're coming from, i seemed to have been slightly lazy with that commit... However, the tool does ensure that the dev has the final say; it will open the user's editor with the commit message that the ai has 'drafted' so the dev can make necessary changes - it provides a starting point that a dev can then tailor.
> However, the tool does ensure that the dev has the final say; it will open the user's editor with the commit message that the ai has 'drafted' so the dev can make necessary changes - it provides a starting point that a dev can then tailor.
The problem with this is that it still biases people towards including useless fluff. I'd almost rather have no commit mesasge whatsoever (so I at least know there's nothing of value there) rather than having to read through paragraphs of text to determine that there was nothing useful to read. I'd much rather have a terse one line sumamry that includes the gist of the intent of the change than a bunch of waffle.
(I'd rather have 1-2 paragraphs of a well-written, accurate description of the content than any of that, but AI unfortunately isn't capable of that).
I’m just going to continue using Jira ticket numbers.
It baffles me how people think git log reading like a novella is a good idea. It’s not, because a cherrypick or merge can/will/should overwrite whatever clever garbage you put in there with its own message. Are you going to summarize Q4’s battle with scaling in a paragraph on the sprint merge to master? No. No you aren’t.
So, while I’m against commit messages saying “fixed”, obviously, I’m equally against a “conversation” in git.
If you have engineers on your team that are anal about commit messages, ask them to be as anal about features and teach them to git diff.
Ticket numbers are good enough as long as they don't rot (i.e. you never permanently delete tickets). That's just writing the "why" somewhere else instead of in the commit message; the important part is that it's written down somewhere and is discoverable/accessible to future folk (yourself included).
I like putting a minimal description in the message itself too so it's easier to skim the log, though.
This is not for me. :) I'd much rather spend my time writing good code than having the AI help me write good commit messages. By not spending time writing good commit messages I have time to write self-explanatory code, for which you don't have to dig through the commit log to figure out what it does.
I applaud your desire to write better commit messages and not be lazy. Not every commit deserves the attention, but being able to turn on "I am definitely going to leave a precise record for the next person to see this diff" is a great skill to have.
However, I feel like your approach here is a little backwards. By getting the AI to come up with the commit messages, you're actually removing the chance for the human, you, to practise and improve.
I'm a real fan of Kahneman's "thinking fast" and "thinking slow" paradigm. By asking the human to review and approve the commit message, you're allowing them to "think fast", instead of doing the challenging, deliberative "thinking slow" of actually writing what you mean.
While getting the LLM to ask you questions about what you did and why is better than just one-shotting the commit message from the diff, it still lets you reply "reactively" and instinctually, using your "fast" gut thinking, instead of engaging the slower attentive processes required to write from scratch.
Now there are a couple of other posters here critiquing the commit messages in this repo's history. I think that's fair, but by your own admission you are learning, and this is a small and new project! Probably most commits should be along the lines of "getting a thing working", not essays about the intricacies of character encoding:
But the commits we can see are already demonstrating some of the pitfalls of LLM generated language.
From a recent commit,
"This update enhances user interaction by explicitly addressing scenarios with large diffs, directing users towards feasible actions and maintaining workflow continuity."
This comes after a detailed breakdown of the diff. It is too vague to stand alone without the preceding detail (e.g. 40k character limit) but also doesn't explain them. Why 40k characters? Why any limit at all? Words like "enhances" and "feasible" are filler - be concrete instead.
This article on wiki has fantastic advice about ways that LLM writing fails, more along the lines of what I've just pointed out:
Writing well is hard, never "effortless" as your readme advertises. Sadly, good results have to come from hundreds of hours of hard and uncomfortable work. Truth is rare and precious and difficult to come by, and even when we glimpse it, turning it into words is a whole nother story. I hope you can continue to develop this tool to help you learn and train your own writing, rather than avoid it.
More drive-by criticism of your commits, meant in a sincere attitude of helping you learn.
As best I can tell, lots of your commits seem to be including several unrelated changes.
This means commit messages become longer as they have to explain more things, and they also end up explaining the diff so that you can fit more on one page.
I'd suggest getting in the habit of making coherent commits with one change each. Some changes will be trivial, and the diff will be self explanatory. Then you can save your writing effort for commits that are challenging.
On the other hand, if I'm wrong and many changes to have to get bundled, then the commit message would be a good place to explain why.
> Probably most commits should be along the lines of "getting a thing working", not essays about the intricacies of character encoding:
I'm not a fan of that commit as a commit, although it would make a great start for a blog post. The explanation of how the issue was tracked down, is not helpful in understanding what the issue is. On the other hand, while the author describes finding (and replacing) a non-ASCII character masquerading as a space, it would have been more interesting to know what character it was.
I agree that explaining the "why" is useful, but in this case I don't think it deserves much more detail than "ensure the file uses only ASCII characters to avoid a text encoding error while running tests in this specific manner". (I guess I can also see the argument for showing the error message for later searches, too....)
I'd rather have that commit message than one that doesn't explain anything, but it's a bit verbose to my taste because I don't really care how he discovered the issue. I really just need to know what and why.
So let me link to my favorite author of consistently excellent commit messages, Jeff King on the git project itself:
To pick just one, here's a well explained single-line code change. It's subtle, so besides the excellent commit messages, he also adds a comment and a couple tests:
Best of luck! A couple of clarifications as I was writing from the train and didn't do a second draft:
By "backwards" I meant to suggest, have the LLM critique a commit message you wrote. Have it point out vague language, weasel words, generalisation and marketing terms.
The wiki article is good advice for writing in general, not limited to LLMs.
When you squash merge almost everything, only the last messages and messages you let to yourself at checkpoints are important. JJ has it right, a message should be optin, not optout.
> Enforce the habit of self-documenting code through better commit messages.
This has nothing to do with self-documenting code. On the contrary, in fact, if I have to resort to checking git history that means the code is not self documenting.
From that description I thought it was going to generate the message directly from the diff and the message not being what you thought it would be would be a signal that the code isn't self documenting.
I was expecting a tool like this to exist. Kudos for actually caring about commit messages. As you can see from some of the comments here, there's a growing cohort of developers who simply don't, which is a shame.
I like the implementation, and how it asks you questions to get you to answer why a change was made, instead of making things up, or simply regurgitating what the code does.
I still wouldn't trust it to be accurate and would have to review it, and I personally dislike the default "LLM style", and I wouldn't want to read these messages or subject other people to them, so I won't be using your tool, but thanks for building and sharing.
All my commit messages are a mess and I spend the time that I have designing and writing code, not figuring out how to make the commit message look pretty. That's what merges are for. I don't see the value of this tbh. Just pedantic time wasting.
I have branches that I work in and fork out from in every direction before merging everything back into master. My branches are messy because they're works in progress so I don't care about the commit messages. For the final merge back into master its a high-level overview of changes. I don't try detail every change. I honestly think that devs obsess too much over this clean commit history thing and that it looks to me like pedantic OCD.
I mean, git lends itself to a lot of approaches, the ultimate goal is that the master repo's main branch has a readable and logical set of commit messages usefully describing every change.
Personally I try to avoid merge commits these days, although that's more of a habit than any reasoned position, as such I make frequent use of rebase/squash to edit previous commit messages. Is that worrying about clean commits?
Have you considered whether you really need to use git? You could just take regular snapshots if you are concerned about needing to revert/undo. Or use a tool like git wip to automatically make commits every time you save, if you really like the git UI.
I mean, git is useful even without "human-readable" commit messages.... 99% of my commit messages are complete garbage ("fixes" "farming, music and shit" "update" ".", etc.)
but in practice it's not a huge problem, IDE shows you the commit history of a specific file so bisecting changes is easy, there's only a few entries with the roughly correct date modifying the file you're looking for :D
"low quality code/commit messages" hasn't really slowed me down so far and probably won't in the future either
ok, but did they have to make commit message required, or is there a way to disable it? i think of git as checkpoints, nothing more. the day i have to explore history is the day i quit.
To understand your point of view, is this because you have seen very bad commit messages (I have too!) like "fixed" repeating 700 times and now come to believe it's a pointless thing in the grand scheme of things anyway?
I think I can understand it to a degree. If the code is well-documented (with comments and design docs) then there really should not be a need to look at the prior state of the code. In an ideal universe, the only things that should matter are what the code currently does and what is being requested that it do new or differently.
That's about as charitable as I can be to their take.
I've worked with 5 different SCMs and I'm convinced that the reason why git repos often have such poor commit messages is because of the git commit style guide. So much of it only makes sense once you realize it's been optimized for like 5 of its original users reading it on 72 character terminal screens.
Asking people to fit a meaningful description of the change into 50 characters is silly, and it's IMO the reason why so many of them just write "fix bug" and call it a day.
Someone else has posted the Google guide for CL (change list) messages, but let me boost the signal: https://google.github.io/eng-practices/review/developer/cl-d...
This is, I believe, still the best guide out there. When I'm coaching juniors, I recommend this guide, over the opinionated and outdated git "best practices" and I think the results are much better.
That Google guide also says that the first line of the commit message should be a "short summary of what is being done". Is your complaint that 50/72 characters is too short? How long can it be before no longer meets the Google criteria, in your opinion?
Yeah, I specifically think 50 is too short. I am a big fan of brevity, but I think the sweet spot is somewhere around 100. Consider that all of these messages exceed the 50-character limit:
They're as short (IMO) as can be without omitting useful information, but git says they're all illegal by some margin.I agree on the value of concise writing and dislike word salads, but if you're a junior engineer, then I have maybe 1 hour with you per week and I probably shouldn't spend that time being your English teacher.
I know I've seen some people recommend 50 (my guess is that's to make some room for metadata from commands like `git log --online` in an 80-column terminal?) but I've personally always capped all lines at 72, including the first. 100 seems like a reasonable limit too, but I probably wouldn't go above that.
> git says they're all illegal by some margin
Git will accept almost anything as a commit message. Is there a specific style guide you're referring to?
---
EDIT: Huh, I guess git does have an official recommendation. I'd never noticed this text in `git help commit`:
> Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description.
I wouldn't feel bad about not following this advice. Even the author doesn't seem dogmatic about it.
> if you're a junior engineer, then I have maybe 1 hour with you per week and I probably shouldn't spend that time being your English teacher
It's not important enough to make a big deal out of, but if I see it over and over from the same person I might mention it during code review ("your commit messages are a bit wordy; for example instead of '…', consider '…'") or write down as part of a style guide (e.g. if we're tagging commits like in your examples, wherever we wrote down the rules for that). It's the same for other unimportant things that it's nice to agree on (e.g. capitalization of initialisms in code—is it `.toJson()` or `.toJSON()`?).
Short is a relative term, and in this sense is relative to the long form explanation of the code.
If a commit is sufficiently complex the long form could be 600 characters and the short form 200.
I may be misunderstanding: are you saying a commit message with a 200-character-long first line could be an example of a "good" message to you/Googlers? To me that seems like something that could almost certainly be summarized further, regardless of how complex the changeset is (if not it's a sign the commit should be broken up into multiple simpler commits).
Can you give me an example of a commit where the "short, focused summary" can only be usefully-expressed in 200+ characters?
Notably, all of the "good" examples in https://google.github.io/eng-practices/review/developer/cl-d... have first lines under 72 characters.
No, I think a reasonable limit is around 100 with the mode being around 80. 50 is not a reasonable limit for a commit message in English.
A good dev isnt necessarily a good writer. Summarising complexity concisely is difficult.
Restrictions lead devs to write to useless messages like 'fixed a bug' rather than messages that are slightly verbose but actually useful.
Most messages wont be 200 chars. But id rather 200 chars of useful text than 72chars of useless text.
The real world is full of average devs that are average writers under time pressure to deliver code. Expecting them to deliver above average commit messages like googles examples is a pipe dream.
> A good dev isnt necessarily a good writer.
I think they should be (or at least "decent").
Should this reasoning be applied to other skills involved in software engineering? If someone never writes tests, or over-architects everything, or has terrible people skills, or never updates documentation, or doesn't bring attention to blockers, or constantly forgets to update the issue tracker, or doesn't follow the local code conventions, or works on random tasks and ignores high-priority ones, etc etc etc the solution isn't usually "don't ask them to do a thing they're bad at", it's "help them get better".
The important question is whether "skimmable commit messages" is a thing you care about enough to advocate for and teach people about. Maybe you don't, and that's fine.
> But id rather 200 chars of useful text than 72chars of useless text.
I completely agree with this. I just don't think those are the only two options.
> Expecting them to deliver above average commit messages like googles examples is a pipe dream.
This thread started with praise for that Google guide and I assumed you were of similar opinion given your reply. That's why I kept referring to it.
Two things:
1. I basically agree with everything you say, I only think the limit should be ~50-100% higher. Not 10x, but 1.5-2x.
2. For some reason, concise writing is the hardest thing to teach and demand consistently. I think a part of is that people try to hide incompetence behind a word salad, but also I think non-native speakers use more words than they need. It gets to a point where you either have to become everyone's English teacher or accept some amount of word salad.
The Google guide assumes a repo other than git. Consider this:
A "tag" means something entirely different to git.This is excellent, thank you! Don't hate me but I'm going to change my Claude Code /commit command by pointing it at this guide.
It probably depends on the codebase, but I find the best motivation for writing solid commit messages is reading commit messages. Tools like gitlens make this really easy.
Almost daily, I use commit messages and history as part of understanding why a decision was made, why a seemingly obvious alternative wasn’t chosen, etc. seeing the commit title on every line, and hovering to see the full message has become a core editor feature for me.
It’s kind of like testing, the more I do it, the more I want to do it because the value is so consistently reinforced.
There’s nothing like being able to track down exactly why a decision was made 6 years ago in a part of the code base you are struggling to understand written by someone who left before you joined the team.
10,000% this. Attaching JIRA tickets, etc. to the commit helps for searching as well. I've worked with a number of people who do not believe in this and it drives me insane ; I try to enforce it, but there's a lot of messages like "fixed bug" that have zero context or detail associated with them.
I don't understand why so many engineers are like this.
Attaching JIRA issues makes a ton of sense for features that are described in JIRA. If we're talking about a bug that was found by a developer, unmotivated by a ticket, it would generally make more sense to just describe the bug directly in the commit message. This is of course not true if the JIRA tickets are used for something else downstream, like informing users of fixed bugs, or tracking changes.
The other issue with tagging JIRA tickets is that junior developers will believe that to be enough (you can just read the ticket) and wont understand why they need to describe the change from a technical angle, when it's already described in JIRA.
Commit messages are immutable. Linking them to a bug ticket gives you a mutable place to record any new information about the bug that you discover in the future. (For example, that it affected more cases than you originally thought, or that the fix caused another bug.) This new information will be discoverable when starting from the original commit (found e.g. by doing a blame on a particular line of source).
To fail to do so is a gigantic missed opportunity in my opinion. You never know when you will need it.
I never have to read git history. So spending time on commit messages is wasted time for me. "Fix bug" is my typical commit message.
Attaching ticket numbers has always been enforced by automated checks wherever I have worked, so it is not necessary to “try” to enforce it.
Similarly with AI it is fairly simple to have eg a pre-merge check that validates the commit msg is somewhat useful. This could be implemented for example with GitHub org level checks that must run in a PR.
YOU should be writing your commit messages, not an AI.
You can always generate a new commit message (or summary, alternative summary, etc) down the road with AI. You can never replace your mind being in the thick of a changeset.
The author of the commit doesn't matter per se. If someone is just having AI summarize their changes and using that as the commit message, I agree that they're doing it wrong.
These days, lots of my commit messages are drafted by AI after having chatted at length about the requirements. If the commit message is wrong or incomplete, I'll revise it by hand or maybe guide the AI in the right direction. That tends to be a much more useful and comprehensive description of the commit's intent than what I would naturally find worthwhile to write on my own.
OP's approach is interesting as well, at least in principle, and if it works well it might be the next best option in the absence of a chat log. It should just make sure to focus on extracting the "why" more than describing the "what".
> than what I would naturally find worthwhile to write on my own.
I take issue with that statement. There's nothing "natural" about documentation. You're not "naturally disposed" to writing a certain level of documentation. It's a skill and a discipline. If you don't think it's worthwhile to write documentation, that's not a "natural failing". You're making a judgment, and any missing documentation is an error in judgment.
I meant "natural" in a context of having more urgent immediate priorities than extensively detailed documentation at the commit level — not an error in judgement, just a tradeoff.
If a given project has time/budget to prioritize consistent rigorous documentation, of course it should consider doing so. AI's ability to reduce the cost of doing so is a good thing.
If we assume, as many do, that we are going to delegate the work of "understanding the code" to AI in the coming years, this surely becomes even more important.
AI writing code and commit messages becomes a loop divorced from human reasoning. Future AIs will need to read the commit history to understand the evolution of the code, and if they're reading poor summaries from other AIs it's just polluting the context window.
Commit messages are documentation for humans and machines.
I have completely opposite opinion on this.
Writing commit messages is one of these mundane chores I’d gladly delegate to LLMs which are very very good at this kind of thing.
I mean, if you really know you code, you know it, there is no much value in reinforcing it in your head one more time via writing comprehensive commit messages - it’s a waste of time, imho.
Neither the code nor the AI know WHY a commit it being made.
This context should at the very least be linked.
For 99% of all commits the WHY is fully answered by the diff itself.
Hard disagree, though it’s probably dependent on your domain and/or how expressive your test suite is.
But even if that were true, reading a two liner explanation is very obviously more time efficient than reviewing a whole commit diff.
Super common case: you got a subtle bug causing unexpected values in data. You know from the db or logs that it started on 2025-03-02. You check the deployment(s)of that day and there are ~20 of them.
You can quickly read 20 lines in the log and have a good guess of which is likely to be related or go for a round of re-reviewing 20 multi file pull requests and reverse engineer the context from code.
"Super common case" is "initial commit", "fix spelling in README.md", or "small refactor". If your "super common case" is "subtle bug causing unexpected values in data" then you are doing something very, very wrong.
Man, 99% of non-bug-fix commits don't have a why other than "advance the current task".
Almost all commits live in tandem with some large feature or change being made. The reason for absolutely all of them is the same - build the thing .
>other than "advance the current task"
How do you expect someone to know what “the current task” was when they’re tracking down a bug 2 years down the line?
Then write that and link to the current task. That's the why. You don't need an LLM for that.
Maybe what we need is a pre-commit hook that prefixes every commit with the name of the branch it's being made onto
Perhaps this is about commit granularity. If keeping the history about advancing the task is not useful, then I’d merge these commits together before merging the PR; in some workflows this is set up to happen automatically too.
I agree in principle, but in practice, it's horrible right now.
Most AI generate commit messages and PR descriptions are much too verbose and contain 0 additional informational value that couldn't be parsed from the code directly. Most of the time I'd rather read 2 sentences written by a human than a wall of text with redundant information.
Sounds like you haven't been working long enough to forget your decisions, which you WILL do eventually. In such cases, where you're looking at code you wrote 10 years ago and you find a weird line, when you view the git blame and read the commit message, you'll be very thankful that you explain not just "what" you did, but "why" you did this, something an AI will have a very hard time doing.
You don't have to if you don't want to, but if you think "this commit message is just a summary of the changes made", you'll never write a useful commit message.
I’ve been working in the industry for two decades, and I think commit messages is not the best place for storing decisions and associated context. I personally prefer ADRs.
Two decades and you don't see any value in writing down what's currently in your head?
Anyhow, ADRs are good, but they stand for Architectural decisions, not every decision is at that level.
In general, if there's a better place to store explanations, do use it, but often, in many projects, commit messages are the least bad place; and it's enormously better to write there than nowhere at all.
Line comments work pretty well for explanation storage. :) Almost every programming language support that feature.
They can sure be good, and are often indeed a better place, but unfortunately most people don't want too many lines of comments in the code.
We sure should have better tools to handle code annotations, but commit messages are a not too bad fallback until we get them
That’s why you put the comment in the code
comments rot as the code changes around them
> I mean, if you really know you code, you know it, there is no much value in reinforcing it in your head one more time via writing comprehensive commit messages - it’s a waste of time, imho.
I know the code...when I write it. But 2 weeks later all the context is gone, and that's just _for me_. For my colleagues who also have to be in that code, they don't even start with context.
I mean do what works for you, but understand the bulk of the work that this applies to is for >1 person shops with code bases too big to fit in ones head at all, much less for more than a day or so.
This reminds me of the time when I put extra effort to write good commit messages, explain 'the theory'[1] behind when it makes sense, name Chesterton's fences and generally provide guidance to the future engineer who has to look through this to understand why something was done in a certain way.
This was a delayed project running out of budget and everything had to be completed within a few months. However, the management in it's infinite wisdom also did a complete source code/issue management platform change.
The person who did the repo migration went with the default settings. (I believe this was the case. I forget the details. I would also only half blame the person because everything was rushed)
Everything up to that point was committed with "Made by so and so bot".
This was way ahead of Google was allegedly committing "well over 30%" of code by AI. I witnessed the true pioneers in this space.
[1] https://pages.cs.wisc.edu/~remzi/Naur.pdf
A lot of developers are afraid of referring to themselves in a commit message. I think this is a mistake. Treat a commit like an email accompanying a patch. Explain to the reader (probably you, five years from now!) why you’re making the changes you are in a conversational, but technical tone.
https://github.com/arpxspace/smartcommit/commit/cc677f7bd210...
This is just a complete braindead commit. Without looking at the code I could probably take 5 minutes to make sense of the commit message, being intrigued something interesting or important is happening. The message is massively over the top, it has way more text then actual code changes. It wastes time.
I am not against AI as a helper in various places. But if possible it should be an opt-in tool if deemed useful. If someone wants to get a summary about a non trivial commit, that can be useful. Even better if the committer writes about the intentions and reasons for the commit, so an AI could match those with the actual code. Don't reiterate whats happening in a patch. Give the meta that isn't there or less obvious. Please.
You see the same with code and text generated by LLMs. Overly verbose, comments that repeat code, and commit messages that repeat what is done in code, but not WHY.
For that matter,
> The full path specification in `go build` was redundant given the context of how Go modules are structured. Simplifying the instructions improves clarity and reduces confusion for new users or contributors.
The explanation doesn't seem quite right. The module mentioned in that command was moved to the project root, in such a way that the command no longer needs to specify a path. So the full path specification wasn't redundant; the updated version of it, became redundant.
And all of this was done in a single commit. Better (disclaimer, I have no experience using Go. Actual Go developers probably don't even need to be told this much):
and then: and then: (No explanation required for the last one.)There's no need to justify that your changes are "in accordance with best practices", tell a story about "ongoing efforts" (unless you actually have other recent commits that you want to group together like that conceptually), etc. Commit messages are for other developers. Another developer who reads, in effect, "this change was made in the hopes that YOU will have an easier time contributing to the project"... is going to feel patronized.
But making fine-grained commits with short messages will help in the long run. No amount of prose in commit messages can actually organize the commits. Meanwhile, the AI's summary completely ignored a change I would recommend splitting out into a separate (third) commit.
This is great advice.
> There's no need to justify that your changes are "in accordance with best practices", tell a story about "ongoing efforts" (unless you actually have other recent commits that you want to group together like that conceptually), etc.
LLMs are very prone to generalisation and marketing language like this. Despite being sycophants, they are also trained to speak as if they constantly have to justify and persuade.
This is called out in the Wikipedia meta I linked to in another comment. They're great red flags to look out for in any writing; humans, myself included, often used this kind of lazy construction!
A bit of prompt engineering should do the trick.
Sigh... Just Send Me the Prompt: https://blog.gpkb.org/posts/just-send-me-the-prompt/
If I needed this LLM output, which I probably don't, but let's say I do, I can just generate this myself. It's disrespectful to others to generate LLM output for them. Just send them the prompt. We all have access to these tools. It's like sending someone a pre-masticated apple. I have my own teeth, thank you.
What you failed to realise is that the 'prompt' has been sent to you - only indirectly, as the project is fully open source. Just look at the source code.
The prompt from that project will be even more worthless, it's just a generic instruction to create a generic summary. It's about having human feedback in commit messages. What are their reasons, problems, intentions for the patch.
https://www.seyhan.me/blog/post/lost-art-of-commit-messages
> For the love of clean code history, let's remember we're not monkeys banging on keyboards; we're educated, civilized human beings.
If you are interested in writing better commit messages on your own, Google's advice makes for a good starting point:
https://google.github.io/eng-practices/review/developer/cl-d...
I also recommend Zulip's guidelines.
https://zulip.readthedocs.io/en/latest/contributing/commit-d...
Thanks for sharing this! This kind of quick and easy grasp one pagers is how this type of things should be done. We should drum it up loud whenever we can.
Core AI model interaction is here https://github.com/arpxspace/smartcommit/blob/main/internal/...
It is fun you have to pre-prompt with: You are an expert software developer.
yes lol...
I also found i had to hold llama3.1's hand more than gpt4o but i suppose that is a given since it's a much smaller model.
> Built this after repeatedly being confused 6 months in a project as to why i made the change i had made...
That might indicate an underlying problem that can’t be fixed with AI. ;)
> strictly enforces the Conventional Commits specification (feat, fix, chore, etc.).
Nope. Waste of bytes in my commit message header that are better done by git trailers.
Otherwise, I love the idea of the tool. I personally try to answer “why does this commit exist?” when I create commits.
I have a coworker that makes every branch into a story about wizards, elfs, or whatever. There's a whole arc that explains the story of the commit in a fun way. I have no idea how he comes up with it all for the past 10 years.
rotfl can you upload some of that somewhere?
I find that the CC structure helps me scan a list of recent commits, e.g. when squashing something into a past commit or trying to find where to navigate.
I don't spend a lot of time on trying to come up with scopes etc, I just make sure that my commit does one thing that fits the label.
Interesting, never knew about git trailers - will have a look!
These categories can be useful, as they indicate part of the “why”. I just heavily dislike the value judgement of “chore”.
I agree, I hate conventional commits. Why the hell do I care if changes are chores or features? I want to know what the change was.
I'm surprised to read that someone not only finds no value in conventional commits, but actively hates it. Wow.
A few reasons to care about CCs:
- The first few characters of a commit message tell you immediately the type of change you should expect. This tells you part of the "what" at a glance. If you're looking for a bug fix, for example, you can safely ignore any other type of commit.
- Thinking about the type of change you're committing helps you create atomic commits. Anything that is not strictly related should go in a separate commit. Hopefully you already know why you should care about this.
- A conventional commit message also often includes the change scope. This is a handy way to indicate the subsystem that was changed, which is also useful for filtering, searching, aggregating, etc.
- They help with writing change logs. I'm a strong proponent of the idea that change logs shouldn't be just autogenerated dumps of commit messages, but carefully redacted for the intended audience, and CCs can help with grouping changes by type or scope. These days LLMs do a decent job at generating this type of changelog (even though it should still be manually reviewed and tweaked), and the additional metadata provided by CCs helps them make it more accurate.
I'm with Ish on this one.
> The first few characters of a commit message tell you immediately the type of change you should expect.
1. Why do I care about this particular classification of "type" of change?
2. "The first few characters" of the message aren't actually what I necessarily see first, anyway.
> If you're looking for a bug fix, for example, you can safely ignore any other type of commit.
1. If I'm looking for a bug fix, I'm using tools like git blame and git bisect.
2. How often do bugs actually get fixed by a single commit, that has that bug fix as their sole purpose, and which is recognized as a bug fix at the time of writing? I'm guessing it's much lower than one would naively expect.
3. If I'm looking for a bug fix, I'm looking for the fix for a specific bug, which is probably most recognizable by some bug tracker issue ID. (And if not, it's most searchable that by figuring out an ID and looking that up). So I'm scanning lines for a # symbol and a number, which I would definitely not expect to be at the start of the line.
> Thinking about the type of change you're committing helps you create atomic commits. Anything that is not strictly related should go in a separate commit. Hopefully you already know why you should care about this.
Yes. And I do this by thinking about a verb that naturally belongs at the beginning of the sentence (fragment) describing the commit. "Bugfix", "feature", and "enhancement" aren't actions.
The discipline of organizing commits is orthogonal to the discipline of labeling them.
> A conventional commit message also often includes the change scope.
One that is thoughtfully written by hand will naturally include the scope of the change any time that this concept is meaningful.
What I don't understand is why you would object to having more metadata attached to your commits. That is essentially what CCs are: additional metadata. Just like the author, date, Co-authored-by, Signed-off-by, and other trailers. It is information that can help you use your Git history in different ways.
You may find no use for this information, or find that it clutters the subject line, but I've addressed both arguments in my previous replies, and won't repeat it here.
> If I'm looking for a bug fix [...]
I mentioned a bug fix as an example, so I'm not sure why you're so focused on that.
CCs introduce a convention to how type and scope are specified. You're not required to use any of the proposed types, and should certainly come up with scopes that make sense for your code base. How you use that information is up to you, and I mentioned several ways that I've personally found it useful.
> The discipline of organizing commits is orthogonal to the discipline of labeling them.
I don't follow. You organize things by grouping them according to some criteria, and labels are required to uniquely identify those groups.
> One that is thoughtfully written by hand will naturally include the scope of the change any time that this concept is meaningful.
Ehm, sure, but CCs provide a framework that standardizes the way information is presented in a well structured repository. A scope is something most repos already use; i.e. it's common to see `<scope>: ...` in repos that don't follow CCs. Attaching a type of commit is another bit of information that further groups commits, and the notation `<type>(<scope>): ...` is just the suggested convention. Which, BTW, naturally came from the way some projects were already structuring their commits.
> I mentioned a bug fix as an example, so I'm not sure why you're so focused on that.
Did you consider it was an example in their comment as well? Fewer features than bug fixes are single commits for example.
> You're not required to use any of the proposed types
> the notation `<type>(<scope>): ...` is just the suggested convention
Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.
The type feat MUST be used when a commit adds a new feature to your application or library.
The type fix MUST be used when a commit represents a bug fix for your application.
A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., fix(parser):[1]
[1] https://www.conventionalcommits.org/en/v1.0.0/
Ha. That's just the language of the RFC specification. This is not some protocol you MUST support exactly as described. It's an attempt at standardizing a convention, and such language makes it easier to follow.
Regardless, blindly following any proposed software development convention or practice is rarely a good idea. It's smarter to get informed, pick and choose practices that make sense to you, and adapt them to your specific workflow.
If you don't find what the Conventional Commits specification proposes valuable, that's fine, but my argument is that it's shortsighted and a mistake. Cheers!
> why you would object to having more metadata attached to your commits
It gets in the way because it takes pride position at the start of the commit message. If you want to put it at the end that might be less annoying but I've never seen anyone do that.
I think the main point is that I almost never arrive at a commit by exhaustively reading through a list of commit messages. It's almost always through some other kind of link like git blame or a GitHub issue/PR.
It's also just really low value information. Imagine if every commit message started with how many lines of code it changed. That would be pretty annoying right?
It's pretty handy when tools like lazy.nvim display changes as a list of commit summaries and you have to make a fast value judgment on if you should allow the upgrade.
Outside of that, I agree that it's silly to put it in the summary and seems to be a symptom of people writing crap commit messages.
If all you ever write or look at is the summary then obviously it needs to go in there or it'll never be seen.
I find value in conventional commits. I do not like so called Conventional Commits. A name which obscures the difference is 1 reason.
Feature and fix are change set types. Not commit types. There is no difference if you squash. There is if you do not.
Many projects which do not use Conventional Commits include scope in commit messages.
Structured change type and scope help to write change logs. An issue tracker is a more useful place for this information in my view.
Eh, I wouldn't say it's a waste of bytes. Conventional Commits are useful for many scenarios.
This metadata could also be added via trailers, but most Git UIs don't show them prominently, or at all. So prefixing the subject is still the way to go.
I’d rather not hack my process around the deficiencies of someone else’s poor UI choices. As long as the data is stored in a powerful, structured format, you can serve that up in any way that’s sensible to you with `git log` and other shell friends.
That's your prerogative, but a) conventions are not "hacks", and b) the main benefit of CCs are their visibility. If most code forge web UIs and standalone tools don't make this information visible, it's not of much use. `git log` is just one way to surface this information, and "shell friends" can also make "poor UI choices".
Most of the time ROI is not there just like with unit tests.
You don’t need 98% of commit messages ever again.
Yes when you need those 2% most likely it is for important reasons but usually not so important to make all the other mulled over.
I don't find commit messages useful for historical reasons (git log), I squash them anyway when merging PR. Commit messages are very helpful to a reviewer to get a necessary context and intent behind the change. Without it, I need to figure out it my self when reviewing. It is very easy to get a habit of committing often and in AI era i don't write commits anymore. So there is no excuse.
The 2% of cases when you need the commit log (or more importantly: someone else who inherits your code...) justifies writing good messages imho.
If you make a change to your codebase, normally you know what you want to achieve and why (otherwise... what are you even doing?). A commit message is just putting that in writing... that only takes a few seconds, often less than it takes to write the code.
So it's just a good habit to have. It forces you to think more about the changes you do & why, so it makes you a better software developer. Creating any new habit always takes some energy initially, but it's worth it.
You know prisoners dilemma - if we even never meet at all it makes even more sense for me to cut the corners.
If we work together for years it makes sense to cooperate.
Unfortunately most IT projects are set up in a way where you do it for 2 years and then you will never ever work on it again.
This will lead to engineers and tech people with less and less communicative skills... Being able to summarise your work and build solid descriptions about the main points of the commit is something so basic that should not be lost... If english is not your main language or you are not that good at writing, I understand that you could make a draft and ask AI to improve it or rewrite it, but this tool is directly a black box that builds the entire commit message based on a couple of prompts, as if it was an impossible task to be done by a human.
No.
Honest to God, this would discourage frequent commits.
Which will lead to a lot of work not being committed.
Thoughtful messages are for PRs.
Alternative: I do a lot of commits just marked "wip" as I go, then when I'm ready to consider a PR, I rebase my branch into something for public consumption. Some commits will get thoughtful messages when warranted, others will get one line, and the PR description will tie it all together with screenshots and links to the most interesting parts.
(On a good day, that is. Though even on a bad day I don't let "wip" commits into the main branch.)
I'd look to Peter Naur's 1985 paper, "Programming as Theory Building," to remind us that writing meaningful commit messages is essential insofar as it is the discipline that confirms and preserves the intellectual "theory" of our work, distinguishing it from mere text production. In Naur's view, programming is fundamentally the activity of builsing theory, which he defines as the knowledge a person must possess not only to intelligently perform tasks, but also to explain them, to answer queries about them, to argue about them, and so forth. The source code is merely an artifact, and neither machine code nor source code contains the wisdom of knowing how the program works, or more critically, why the program was written the way it was instead of some other way that would have accomplished the same task.
The act of composing a descriptive and concise commit message compels the programmer to transition from the task of "path-making" (writing code) to the intellectual work of explaining the process, which is necessary to grok the change completely.
Reviving the theory of an existing program is a difficult, cult-frustrating, and time-consuming effort. When theory-building is neglected, we lose the intellectual foundation that dictates the program's purpose and design, trapping future maintenance efforts in a costly, confusing cycle of trying to deduce intent from artifact alone
If a bug was fixed I usually paste the error traceback into the commit description
Meaningful commit messages are meant to be read later and be useful. I'm not going to read through 8 sentences of generated slop, would rather look through the diff.
Obligatory "show me the prompt" https://news.ycombinator.com/item?id=39374249
I'm assuming the commits in the repo were generated with the tool itself. In that case, commit `cc677f7` has a (in my opinion) terrible commit message. It starts out with a listing of stuff I could just as well read from the patch. It then contains another list that tries to explain the why, but it ends up being useless fluff like `The full path specification in `go build` was redundant given the context of how Go modules are structured.` and `streamlining the project structure and reducing unnecessary directory complexity.` which tells me exactly nothing about why those changes were made.
It generates a whole lot of text that makes me none the wiser as to why you wanted to do any of those changes. It feels like a robot trying to justify the changes post hoc. Which it of course is, so that's understandable.
Don't take this comment as rudeness BTW. It's cool that you're making a fun little tool. I'm assuming you care about writing more useful commit messages, so I thought I'd give you some feedback on that part.
Yeah totally see where you're coming from, i seemed to have been slightly lazy with that commit... However, the tool does ensure that the dev has the final say; it will open the user's editor with the commit message that the ai has 'drafted' so the dev can make necessary changes - it provides a starting point that a dev can then tailor.
> However, the tool does ensure that the dev has the final say; it will open the user's editor with the commit message that the ai has 'drafted' so the dev can make necessary changes - it provides a starting point that a dev can then tailor.
The problem with this is that it still biases people towards including useless fluff. I'd almost rather have no commit mesasge whatsoever (so I at least know there's nothing of value there) rather than having to read through paragraphs of text to determine that there was nothing useful to read. I'd much rather have a terse one line sumamry that includes the gist of the intent of the change than a bunch of waffle.
(I'd rather have 1-2 paragraphs of a well-written, accurate description of the content than any of that, but AI unfortunately isn't capable of that).
> The problem with this is that it still biases people towards including useless fluff.
The developer now has to choose "do I spend the time to make this commit message better?" or just skim it and say "yeah that's good enough."
Write a commit message for your future self
Future self won't understand the code and the message. ;)
... Or your future AI agent
I’m just going to continue using Jira ticket numbers.
It baffles me how people think git log reading like a novella is a good idea. It’s not, because a cherrypick or merge can/will/should overwrite whatever clever garbage you put in there with its own message. Are you going to summarize Q4’s battle with scaling in a paragraph on the sprint merge to master? No. No you aren’t.
So, while I’m against commit messages saying “fixed”, obviously, I’m equally against a “conversation” in git.
If you have engineers on your team that are anal about commit messages, ask them to be as anal about features and teach them to git diff.
Ticket numbers are good enough as long as they don't rot (i.e. you never permanently delete tickets). That's just writing the "why" somewhere else instead of in the commit message; the important part is that it's written down somewhere and is discoverable/accessible to future folk (yourself included).
I like putting a minimal description in the message itself too so it's easier to skim the log, though.
Nice! Most of my commit messages end up being something like "fixes and stuff, this works now!". This can be pretty helpful
This is not for me. :) I'd much rather spend my time writing good code than having the AI help me write good commit messages. By not spending time writing good commit messages I have time to write self-explanatory code, for which you don't have to dig through the commit log to figure out what it does.
I applaud your desire to write better commit messages and not be lazy. Not every commit deserves the attention, but being able to turn on "I am definitely going to leave a precise record for the next person to see this diff" is a great skill to have.
However, I feel like your approach here is a little backwards. By getting the AI to come up with the commit messages, you're actually removing the chance for the human, you, to practise and improve.
I'm a real fan of Kahneman's "thinking fast" and "thinking slow" paradigm. By asking the human to review and approve the commit message, you're allowing them to "think fast", instead of doing the challenging, deliberative "thinking slow" of actually writing what you mean.
While getting the LLM to ask you questions about what you did and why is better than just one-shotting the commit message from the diff, it still lets you reply "reactively" and instinctually, using your "fast" gut thinking, instead of engaging the slower attentive processes required to write from scratch.
Now there are a couple of other posters here critiquing the commit messages in this repo's history. I think that's fair, but by your own admission you are learning, and this is a small and new project! Probably most commits should be along the lines of "getting a thing working", not essays about the intricacies of character encoding:
https://dhwthompson.com/2019/my-favourite-git-commit
But the commits we can see are already demonstrating some of the pitfalls of LLM generated language.
From a recent commit,
"This update enhances user interaction by explicitly addressing scenarios with large diffs, directing users towards feasible actions and maintaining workflow continuity."
This comes after a detailed breakdown of the diff. It is too vague to stand alone without the preceding detail (e.g. 40k character limit) but also doesn't explain them. Why 40k characters? Why any limit at all? Words like "enhances" and "feasible" are filler - be concrete instead.
This article on wiki has fantastic advice about ways that LLM writing fails, more along the lines of what I've just pointed out:
https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing
Writing well is hard, never "effortless" as your readme advertises. Sadly, good results have to come from hundreds of hours of hard and uncomfortable work. Truth is rare and precious and difficult to come by, and even when we glimpse it, turning it into words is a whole nother story. I hope you can continue to develop this tool to help you learn and train your own writing, rather than avoid it.
More drive-by criticism of your commits, meant in a sincere attitude of helping you learn.
As best I can tell, lots of your commits seem to be including several unrelated changes.
This means commit messages become longer as they have to explain more things, and they also end up explaining the diff so that you can fit more on one page.
I'd suggest getting in the habit of making coherent commits with one change each. Some changes will be trivial, and the diff will be self explanatory. Then you can save your writing effort for commits that are challenging.
On the other hand, if I'm wrong and many changes to have to get bundled, then the commit message would be a good place to explain why.
I wrote more on the "primitives" and what I think of as the "physics" of commits here: https://crabmusket.net/2024/thoughts-on-git-commits-branches...
> Probably most commits should be along the lines of "getting a thing working", not essays about the intricacies of character encoding:
I'm not a fan of that commit as a commit, although it would make a great start for a blog post. The explanation of how the issue was tracked down, is not helpful in understanding what the issue is. On the other hand, while the author describes finding (and replacing) a non-ASCII character masquerading as a space, it would have been more interesting to know what character it was.
I agree that explaining the "why" is useful, but in this case I don't think it deserves much more detail than "ensure the file uses only ASCII characters to avoid a text encoding error while running tests in this specific manner". (I guess I can also see the argument for showing the error message for later searches, too....)
I agree with you.
More on the subject: https://mtlynch.io/no-longer-my-favorite-git-commit/
I'd rather have that commit message than one that doesn't explain anything, but it's a bit verbose to my taste because I don't really care how he discovered the issue. I really just need to know what and why.
So let me link to my favorite author of consistently excellent commit messages, Jeff King on the git project itself:
https://github.com/git/git/commits?author=peff
To pick just one, here's a well explained single-line code change. It's subtle, so besides the excellent commit messages, he also adds a comment and a couple tests:
https://github.com/git/git/commit/1940a02dc1122d15706a7051ee...
Another example with an even greater ratio of explanation (10 paragraphs) to code (partial line change):
https://github.com/git/git/commit/8f32a5a6c050766bfa2827869e...
Oh these are great examples, thank you!
This is amazing, thank you! Will definitely take this on board for the next iteration of this tool. I wholeheartedly agree with the perspective of:
> develop this tool to help you learn and train your own writing, rather than avoid it
Will be striving for this for sure.
Best of luck! A couple of clarifications as I was writing from the train and didn't do a second draft:
By "backwards" I meant to suggest, have the LLM critique a commit message you wrote. Have it point out vague language, weasel words, generalisation and marketing terms.
The wiki article is good advice for writing in general, not limited to LLMs.
When you squash merge almost everything, only the last messages and messages you let to yourself at checkpoints are important. JJ has it right, a message should be optin, not optout.
> Enforce the habit of self-documenting code through better commit messages.
This has nothing to do with self-documenting code. On the contrary, in fact, if I have to resort to checking git history that means the code is not self documenting.
From that description I thought it was going to generate the message directly from the diff and the message not being what you thought it would be would be a signal that the code isn't self documenting.
I was expecting a tool like this to exist. Kudos for actually caring about commit messages. As you can see from some of the comments here, there's a growing cohort of developers who simply don't, which is a shame.
I like the implementation, and how it asks you questions to get you to answer why a change was made, instead of making things up, or simply regurgitating what the code does.
I still wouldn't trust it to be accurate and would have to review it, and I personally dislike the default "LLM style", and I wouldn't want to read these messages or subject other people to them, so I won't be using your tool, but thanks for building and sharing.
All good - appreciate the feedback!
Writing meaningful commit messages is an absolute time-wasting nonsense.
All my commit messages are a mess and I spend the time that I have designing and writing code, not figuring out how to make the commit message look pretty. That's what merges are for. I don't see the value of this tbh. Just pedantic time wasting.
When these people say "commit" they're referring to the same concept you "merge".
I have branches that I work in and fork out from in every direction before merging everything back into master. My branches are messy because they're works in progress so I don't care about the commit messages. For the final merge back into master its a high-level overview of changes. I don't try detail every change. I honestly think that devs obsess too much over this clean commit history thing and that it looks to me like pedantic OCD.
I mean, git lends itself to a lot of approaches, the ultimate goal is that the master repo's main branch has a readable and logical set of commit messages usefully describing every change.
Personally I try to avoid merge commits these days, although that's more of a habit than any reasoned position, as such I make frequent use of rebase/squash to edit previous commit messages. Is that worrying about clean commits?
Not really, necessarily
On a personal project I've decided to do the opposite and every commit message is meow or mlem or hisssss or purrrr etc
Have you considered whether you really need to use git? You could just take regular snapshots if you are concerned about needing to revert/undo. Or use a tool like git wip to automatically make commits every time you save, if you really like the git UI.
I mean, git is useful even without "human-readable" commit messages.... 99% of my commit messages are complete garbage ("fixes" "farming, music and shit" "update" ".", etc.)
but in practice it's not a huge problem, IDE shows you the commit history of a specific file so bisecting changes is easy, there's only a few entries with the roughly correct date modifying the file you're looking for :D
"low quality code/commit messages" hasn't really slowed me down so far and probably won't in the future either
ok, but did they have to make commit message required, or is there a way to disable it? i think of git as checkpoints, nothing more. the day i have to explore history is the day i quit.
To understand your point of view, is this because you have seen very bad commit messages (I have too!) like "fixed" repeating 700 times and now come to believe it's a pointless thing in the grand scheme of things anyway?
> the day i have to explore history is the day i quit.
Huh? I do that all the time, and it's really useful. What is difficult or problematic about it?
I think I can understand it to a degree. If the code is well-documented (with comments and design docs) then there really should not be a need to look at the prior state of the code. In an ideal universe, the only things that should matter are what the code currently does and what is being requested that it do new or differently.
That's about as charitable as I can be to their take.
One particular cynical reading of that could be "the day I'm held responsible for my code is the day I quit".
totally. the fact git-quicksave isn't a standard command that commits with an "Autosave" message is pretty short-sighted.
This thread makes me weep for software engineering.
If it wasn't obvious I am not serious. On the contrary I'm actively making contributions to jujutsu (none involving a quicksave command... yet)
Poe's law strikes again. But really, there is no way to tell you weren't serious, considering the commenter you replied to most certainly is.
I mean, look at this abomination: https://github.com/denys-olleik/alternative-accounting/commi...