9 ms·

Show HN: Build the habit of writing meaningful commit messages

110 points by Aplikethewatch 11mo ago

Too often I find myself being lazy with commit messages. But I don't want AI to write them for me... only i truly know why i wrote the code i did. So why don't i get AI to help me get that into words from my head? That's what i built: smartcommit asks you questions about your changes, then helps you articulate what you already know into a proper commit message. Captures the what, how, and why. Built this after repeatedly being confused 6 months in a project as to why i made the change i had made... Would love feedback!

teeray 11mo ago
> 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.
- Aplikethewatch 11mo ago
  Interesting, never knew about git trailers - will have a look!
- withinboredom 11mo ago
  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.
  - g-b-r 11mo ago
    rotfl can you upload some of that somewhere?
- imiric 11mo ago
  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.
  - teeray 11mo ago
    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.
    - imiric 11mo ago
      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".
- IshKebab 11mo ago
  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.
  - imiric 11mo ago
    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.
    - zahlman 11mo ago
      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.
- layer8 11mo ago
  These categories can be useful, as they indicate part of the “why”. I just heavily dislike the value judgement of “chore”.
- crabmusket 11mo ago
  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.
philipwhiuk 11mo ago
Core AI model interaction is here https://github.com/arpxspace/smartcommit/blob/main/internal/ai/ai.go https://github.com/arpxspace/smartcommit/blob/main/internal/... It is fun you have to pre-prompt with: You are an expert software developer.
- Aplikethewatch 11mo ago
  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.
delusional 11mo ago
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.
- Aplikethewatch 11mo ago
  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.
  - nicoburns 11mo ago
    > 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).
Uptrenda 11mo ago
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.
- wredcoll 11mo ago
  When these people say "commit" they're referring to the same concept you "merge".
  - g-b-r 11mo ago
    Not really, necessarily
  - Uptrenda 11mo ago
    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.
    - wredcoll 11mo ago
      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?
journal 11mo ago
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.
- landr0id 11mo ago
  totally. the fact git-quicksave isn't a standard command that commits with an "Autosave" message is pretty short-sighted.
  - imiric 11mo ago
    This thread makes me weep for software engineering.
    - landr0id 11mo ago
      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)
      - imiric 11mo ago
        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/commits/main/ https://github.com/denys-olleik/alternative-accounting/commi...
- pxc 11mo ago
  > 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?
  - tazjin 11mo ago
    One particular cynical reading of that could be "the day I'm held responsible for my code is the day I quit".
deleted 11mo ago
[deleted]
imiric 11mo ago
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.
- Aplikethewatch 11mo ago
  All good - appreciate the feedback!
samtheprogram 11mo ago
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.
- ekropotin 11mo ago
  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.
  - deleted 11mo ago
    [deleted]
  - lelandbatey 11mo ago
    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.
    - ekropotin 11mo ago
      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.
      - g-b-r 11mo ago
        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.
crabmusket 11mo ago
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 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 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.
- Aplikethewatch 11mo ago
Yokohiii 11mo ago
https://github.com/arpxspace/smartcommit/commit/cc677f7bd2106e8f0c3d91d307146404d9037501 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.
- Aplikethewatch 11mo ago
  A bit of prompt engineering should do the trick.
- OptionOfT 11mo ago
  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.
- zahlman 11mo ago
  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): 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.
tmoertel 11mo ago
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-descriptions.html https://google.github.io/eng-practices/review/developer/cl-d...
- chanux 11mo ago
  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.
- crabmusket 11mo ago
  I also recommend Zulip's guidelines. https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html https://zulip.readthedocs.io/en/latest/contributing/commit-d...
n8cpdx 11mo ago
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.
- necrotic_comp 11mo ago
  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.
  - tionate 11mo ago
    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.
  - delusional 11mo ago
    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.
ivanjermakov 11mo ago
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 https://news.ycombinator.com/item?id=39374249
999900000999 11mo ago
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.
- crabmusket 11mo ago
  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.)
chanux 11mo ago
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 https://pages.cs.wisc.edu/~remzi/Naur.pdf
layer8 11mo ago
> 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. ;)
cynicalsecurity 11mo ago
Writing meaningful commit messages is an absolute time-wasting nonsense.
purge12 11mo ago
Nice! Most of my commit messages end up being something like "fixes and stuff, this works now!". This can be pretty helpful
ozim 11mo ago
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.
- mirzap 11mo ago
  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.
- vekker 11mo ago
  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.
  - ozim 11mo ago
    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.
aaronbrethorst 11mo ago
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.
xfeeefeee 11mo ago
On a personal project I've decided to do the opposite and every commit message is meow or mlem or hisssss or purrrr etc
- globular-toast 11mo ago
  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.
  - Pannoniae 11mo ago
    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
globular-toast 11mo ago
> 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.
tamnd 11mo ago
https://www.seyhan.me/blog/post/lost-art-of-commit-messages 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.
t8sr 11mo ago
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-descriptions.html 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.
- Croak 11mo ago
  [dead]
- matt_kantor 11mo ago
  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?
  - Xss3 11mo ago
    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.
    - matt_kantor 11mo ago
      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-descriptions.html https://google.github.io/eng-practices/review/developer/cl-d... have first lines under 72 characters.
bjourne 11mo ago
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.
reactordev 11mo ago
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.
- matt_kantor 11mo ago
  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.
hamdouni 11mo ago
Write a commit message for your future self
- hamdouni 11mo ago
  ... Or your future AI agent
- 0x073 11mo ago
  Future self won't understand the code and the message. ;)
kurokawad 11mo ago
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.
BiteCode_dev 11mo ago
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.
gavmor 11mo ago
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
xk3 11mo ago
If a bug was fixed I usually paste the error traceback into the commit description
tabbott 11mo ago
I like that this tries to extract from the human the information that they didn't provide in their initial commit message. So many tools go the direction of asking AI to generate a commit message for you, which will spend most of its space repeating in long form information available in the Git metadata, like the list of files changed. And one can't really expect it to do a great job, if the information of "why did you change this?" wasn't available to it.

110 points by Aplikethewatch 11mo ago

teeray 11mo ago

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

Aplikethewatch 11mo ago
Interesting, never knew about git trailers - will have a look!
withinboredom 11mo ago
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.
- g-b-r 11mo ago
  rotfl can you upload some of that somewhere?
imiric 11mo ago
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.
- teeray 11mo ago
  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.
  - imiric 11mo ago
    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".
IshKebab 11mo ago
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.
- imiric 11mo ago
  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.
  - zahlman 11mo ago
    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.
layer8 11mo ago
These categories can be useful, as they indicate part of the “why”. I just heavily dislike the value judgement of “chore”.
crabmusket 11mo ago
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.

philipwhiuk 11mo ago

Core AI model interaction is here https://github.com/arpxspace/smartcommit/blob/main/internal/ai/ai.go https://github.com/arpxspace/smartcommit/blob/main/internal/... It is fun you have to pre-prompt with: You are an expert software developer.

Aplikethewatch 11mo ago
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.

delusional 11mo ago

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.

Aplikethewatch 11mo ago
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.
- nicoburns 11mo ago
  > 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).

Uptrenda 11mo ago

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.

wredcoll 11mo ago
When these people say "commit" they're referring to the same concept you "merge".
- g-b-r 11mo ago
  Not really, necessarily
- Uptrenda 11mo ago
  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.
  - wredcoll 11mo ago
    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?

journal 11mo ago

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.

landr0id 11mo ago
totally. the fact git-quicksave isn't a standard command that commits with an "Autosave" message is pretty short-sighted.
- imiric 11mo ago
  This thread makes me weep for software engineering.
  - landr0id 11mo ago
    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)
    - imiric 11mo ago
      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/commits/main/ https://github.com/denys-olleik/alternative-accounting/commi...
pxc 11mo ago
> 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?
- tazjin 11mo ago
  One particular cynical reading of that could be "the day I'm held responsible for my code is the day I quit".

deleted 11mo ago

[deleted]

imiric 11mo ago

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.

Aplikethewatch 11mo ago
All good - appreciate the feedback!

samtheprogram 11mo ago

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.

ekropotin 11mo ago
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.
- deleted 11mo ago
  [deleted]
- lelandbatey 11mo ago
  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.
  - ekropotin 11mo ago
    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.
    - g-b-r 11mo ago
      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.

crabmusket 11mo ago

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

Aplikethewatch 11mo ago

Yokohiii 11mo ago

https://github.com/arpxspace/smartcommit/commit/cc677f7bd2106e8f0c3d91d307146404d9037501 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.

Aplikethewatch 11mo ago
A bit of prompt engineering should do the trick.
OptionOfT 11mo ago
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.
zahlman 11mo ago
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): 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.

tmoertel 11mo ago

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-descriptions.html https://google.github.io/eng-practices/review/developer/cl-d...

chanux 11mo ago
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.
crabmusket 11mo ago
I also recommend Zulip's guidelines. https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html https://zulip.readthedocs.io/en/latest/contributing/commit-d...

n8cpdx 11mo ago

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.

necrotic_comp 11mo ago
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.
- tionate 11mo ago
  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.
- delusional 11mo ago
  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.

ivanjermakov 11mo ago

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 https://news.ycombinator.com/item?id=39374249

999900000999 11mo ago

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.

crabmusket 11mo ago
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.)

chanux 11mo ago

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 https://pages.cs.wisc.edu/~remzi/Naur.pdf

layer8 11mo ago

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

cynicalsecurity 11mo ago

Writing meaningful commit messages is an absolute time-wasting nonsense.

purge12 11mo ago

Nice! Most of my commit messages end up being something like "fixes and stuff, this works now!". This can be pretty helpful

ozim 11mo ago

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.

mirzap 11mo ago
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.
vekker 11mo ago
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.
- ozim 11mo ago
  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.

aaronbrethorst 11mo ago

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.

xfeeefeee 11mo ago

On a personal project I've decided to do the opposite and every commit message is meow or mlem or hisssss or purrrr etc

globular-toast 11mo ago
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.
- Pannoniae 11mo ago
  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

globular-toast 11mo ago

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

tamnd 11mo ago

https://www.seyhan.me/blog/post/lost-art-of-commit-messages 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.

t8sr 11mo ago

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

Croak 11mo ago
[dead]
matt_kantor 11mo ago
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?
- Xss3 11mo ago
  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.
  - matt_kantor 11mo ago
    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-descriptions.html https://google.github.io/eng-practices/review/developer/cl-d... have first lines under 72 characters.

bjourne 11mo ago

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.

reactordev 11mo ago

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.

matt_kantor 11mo ago
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.

hamdouni 11mo ago

Write a commit message for your future self

hamdouni 11mo ago
... Or your future AI agent
0x073 11mo ago
Future self won't understand the code and the message. ;)

kurokawad 11mo ago

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.

BiteCode_dev 11mo ago

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.

gavmor 11mo ago

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

xk3 11mo ago

If a bug was fixed I usually paste the error traceback into the commit description

tabbott 11mo ago

I like that this tries to extract from the human the information that they didn't provide in their initial commit message. So many tools go the direction of asking AI to generate a commit message for you, which will spend most of its space repeating in long form information available in the Git metadata, like the list of files changed. And one can't really expect it to do a great job, if the information of "why did you change this?" wasn't available to it.