Thread

Commit description as a thinking tool

129 points · 77 comments · yedhukrishnan

Loading the complete thread in the background. This saved snapshot is available now. Refresh

tombert · 1790791279 · focus · HN ↗
Tangential, but very early in my career, back when I was still using SVN at work, I used to write all my commits in either limerick or haiku, usually smuggling in some curse word(s) with some cheeky message in there. I was convinced that no one actually read them and I could get a laugh out of it.
I did this for months without anyone noticing, and eventually my manager schedules a very awkward meeting asking me why I wrote saying “cfquery fucking blows sometimes”. I had to sheepishly explain that I thought it was funny and then I stopped doing that and my commits became much more utilitarian and much less fun.
1. blmarket · 1790791672 · focus · HN ↗
  I would encourage to speak up - especially when we're blaming bad code(not a person) being bad. Ultimately senior engineers are ones who can blame bad things with a compelling reason.
  1. tombert · 1790792677 · focus · HN ↗
    This was a long time ago so I can't remember the details, and I was decidedly not a senior engineer at the time. That said, if I remember correctly there was something a bit finnicky with how `cfquery` in ColdFusion handled the automatic caching stuff.
FLeXMurphy · 1790791440 · focus · HN ↗
This has been a topic belabored since commit messages were a thing. CVS? RCS Probably earlier.
kccqzy · 1790791766 · focus · HN ↗
Long ago I changed the default commit message to include headers “Why?” and “How?” to remind myself that I need to explain why a change is made (what this article focuses on), and how it is made (different implementation approaches considered). I followed this format for a long time. I was in the top 1% for commit message length at the company.
Tangent: I once worried about things breaking when commit messages got too long. I tried really long commit messages and nothing broke: <a href="https://github.com/kccqzy/long-commit-messages/commit/ccfda400ebe0248ca4a37d1a087507c7dd455a3b" rel="nofollow">https://github.com/kccqzy/long-commit-messages/commit/ccfda4...
1. sublinear · 1790793835 · focus · HN ↗
  To stay concise, I think bullet trees are the best. I've never had to make exceptions to this format.
  Top level groups high-level concerns (optional). Below that (required) are short distillations of those concerns answering "why". Below that are descriptions of "what" was/wasn't done. A final optional level digs into deeper implementation detail.
  The vast majority of my bullet trees are just those two required levels. Each commit message is rarely more than 10 or 15 lines long, and people really appreciate them. I appreciate them too since I'm the most likely to read them.
  1. tommica · 1790796123 · focus · HN ↗
    Got an example of what you mean?
    sublinear · 1790808730 · focus · HN ↗
    A made up example would be something like this.
    MYPRJ-73: Auth bug causing redirect loop - Frontend router fixes - Check cookies before redirect - Default redirect to login page - New case added for "expired" - Backend - Update Apache config - Remove old DBM - Update cookie response header - Don't use "SameSite=Strict" - Removed 3rd-party lib - We own this code for now
    tommica · 1790944737 · focus · HN ↗
    Interesting, thanks for sharing. Need to try it out!
2. nsingh2 · 1790794491 · focus · HN ↗
  Related, I also noticed the Codex repo doing something similar <a href="https://github.com/openai/codex/commits/main/" rel="nofollow">https://github.com/openai/codex/commits/main/
3. cerved · 1790796684 · focus · HN ↗
  I like the Git rule of thumb. If it's too long -- it's probably not a single commit.
4. lokar · 1790803113 · focus · HN ↗
  Why make this change at all? Why do it this way? What would have been the next best way, and why not that? What important assumptions justify this? What's next for this? etc
zahrevsky · 1790791974 · focus · HN ↗
I sometimes struggle to decide whether to put an explanation in a commit message, in the docs (say in an ADR). I tend to save everything as docs because files are a more “universal” interface, so to speak. They’re in plain sight and harder to miss.
I guess the main advantages of Git history are that it’s (1) uneditable and (2) directly linked to a specific commit.
1. mopsi · 1790803756 · focus · HN ↗
  There's an additional aspect: whoever ends up reading the messages later might not even be aware that there is more information somewhere else.
2. tux404 · 1790841880 · focus · HN ↗
  I usually go for very brief commit messages, one-liners preferentially. I would just write something on the body when I feel it call for more detailed explanation or if the reason isn't too obvious. I started using plain markdown for the "why" for each project, status, changelog, bugs etc. Every change to the notes is a commit and git became an audit trail with all the dated, uneditable record of all the decisions and changes. Markdown files won it for me because they are the first thing I read when I get back to a project and also because of the ease of access to AI tools.
  The caveat is that docs can go stale while commit messages can't, it forces you to be extra careful so to be sure that the files are being correctly updated, I took care of that with a simple script that checks all the notes.
3. beybol · 1790858941 · focus · HN ↗
  In my projects WHY always goes to ADR because every decision should be well documented, not only as a comment but with arguments. Moreover a decision may change and the change should be documented too. A published commit message is unchangeable. In one of my projects I have 170 commits and 85 ADRs where one is accepted temporary and one superseded by another.
helloimgkeep · 1790792088 · focus · HN ↗
[dead]
sublinear · 1790792688 · focus · HN ↗
This problem has nothing to do with git.
The journaling of any iterative process requires clear notes that answer "why?" for each step. This is what will guide future maintenance.
Writing code faster than you can digest and explain it is at odds with this. You will incur runaway technical debt. This was already a problem long before the LLM era.
It is nice that more people are finally realizing this, but I'm still waiting for when we start speaking in generalities again and get over all the hype. Nothing ages writing faster than bringing up the specific tools.
seunosewa · 1790793463 · focus · HN ↗
I use a different LLM family to review commits and write detailed descriptions. If a commit was written with Fable/Opus, I use Sol/Astra to write a well reasoned commit message. If the message doesn't match my intent, then that triggers a manual review.
1. _verandaguy · 1790793580 · focus · HN ↗
  The blog post is advocating against this.
2. dennisy · 1790793604 · focus · HN ↗
  This would have an even greater loss of the “why” context the author is describing in the piece.
  1. seunosewa · 1790804144 · focus · HN ↗
    The human knows the "why", so they can correct the commit message if it is wrong or incomplete. Most of the time, though, they don't have to do that.
3. loopmonster · 1790793643 · focus · HN ↗
  If the second LLM is just describing the content of the commit doesn't that defeat the purpose of the description, to capture the context that doesn't make it to the code?
  1. seunosewa · 1790794092 · focus · HN ↗
    The second LLM is prompted to actually research the code, not just the diff, with fresh eyes to figure out what it does and why, before writing the message. If the commit message matches what the first model was asked to write and why, I reckon that it's a good diff.
    GrinningFool · 1790795197 · focus · HN ↗
    But the code doesn't always have the answer to "why". At best that means the commit-writer has 'guessed' at why.
4. cerved · 1790793714 · focus · HN ↗
  If you ask an LLM to write a message that explains "the why", it'll make up a why.
  1. seunosewa · 1790849913 · focus · HN ↗
    So we can read it, and correct it in the occasional event that its wrong.
5. bigmadshoe · 1790793868 · focus · HN ↗
  This makes no sense to me. The code is already self-documenting if written well. Doesn't the original conversation at least retain the context about why the change was made? A different LLM literally has no way to tell why you made this change besides guessing from the codebase and git history.
  1. sigbottle · 1790794182 · focus · HN ↗
    the mechanism is self documenting; context is not unless you pollute all your files with an ADR's worth of alternatives.
  2. seunosewa · 1790794783 · focus · HN ↗
    If a change makes sense, a different frontier model can usually figure out why it was made from the code alone. I take that as a signal that that the commit is good.
    I believe they can do this due to having millions of public pull requests and github issues in their training data.
    cerved · 1790796798 · focus · HN ↗
    There's pretty much always several plausible reasons for why a change was made. What's interesting is knowing exactly which one, especially when it later turns out to be wrong!
    bigmadshoe · 1790800586 · focus · HN ↗
    What a change does is self documenting. Why it was made and why that specific approach was chosen could be due to many things, such as:
    * business objectives,
    * the result of experimentation,
    * the result of an offline conversation
    etc.
    This cannot be captured in code alone. This is why we write commit messages.
6. seunosewa · 1791128367 · focus · HN ↗
  I think my process got read as "let an LLM guess the why and ship it." It's not.
  1. I work in small features. I know what I want before the code exists, and I prompt for it. 2. A model from a different family then reads the code cold, without my prompt or the first model's chat, and writes a message explaining what changed and why. 3. I read that message against what I intended. If it states the wrong reason, I see the mismatch. If it misses something only I know, like a business reason or "temporary until X," I add it. The final why always comes from me, either confirmed or written.
dmtry · 1790793917 · focus · HN ↗
I like git-notes (<a href="https://git-scm.com/docs/git-notes" rel="nofollow">https://git-scm.com/docs/git-notes) for this sort of annotations and context. It's a nice balance - adjacent to commits, follows branch structure, easy to instrument, doesn't muddy the commit history.
Being able to stick a bit of directive text somewhere durable at any point in time has been surprisingly convenient for steering LLMs, as well.
1. cerved · 1790794077 · focus · HN ↗
  why not both? notes are pretty ephemeral by design
WD-42 · 1790794002 · focus · HN ↗
Writing is thinking in every situation, not just limited to commit messages. This is a fact that I'm concerned people are forgetting, or worse never understood to begin with.
1. fasterik · 1790796941 · focus · HN ↗
  This. I've recently (re-)discovered the importance of using writing to force myself to confront my assumptions and gaps in knowledge. It's easy to fool yourself into thinking that you understand something if you haven't made it concrete and explicit by exercising your own brain. Arguably, this extends beyond writing in the conventional sense to many cognitive domains: mathematics, programming, physics, engineering, etc. AI should help the process of thinking, not replace it.
  1. msdz · 1790799829 · focus · HN ↗
    Your point rings home hard to me at the moment, as I’ve recently been trying to write up several small-ish topics in blog form, so as to have a link ready to share when an oft-discussed topic inevitably comes up again online, and some of those arguments, while I had read up on them in the past, include things I’m not entirely familiar with.
    And I’ll just say, after this exercise I can definitely concur that writing exposes gaps in your thinking very fast.
2. ModernMech · 1790798155 · focus · HN ↗
  Did you think about this comment or are you just repeating something you heard and that’s been said in every discussion on HN about writing and AI?
  1. WD-42 · 1790798451 · focus · HN ↗
    I read the linked article, thought the idea was generalizable, and posted that thought. Something wrong with that?
    ModernMech · 1790800518 · focus · HN ↗
    "Writing is thinking" is being repeated all the time lately to the point it seems like a meme, which would be an example of writing that doesn't take thinking.
    WD-42 · 1790801324 · focus · HN ↗
    Does that make it untrue?
    ModernMech · 1790801664 · focus · HN ↗
    I would say probably most memeing is not really thought provoking or inducing. I agree most of the time writing can help collect one's thoughts but it can also be completely thoughtless. Probably what matters more is the specific process.
    bunderbunder · 1790804247 · focus · HN ↗
    I would say that accusing someone of not doing their own thinking just because you've heard the thought before, isn't particularly thought provoking, either.
    If you do disagree with the idea, though, I would love to hear why because that could indeed be thought provoking. But I don't really feel like the above comment fits the bill. I believe we can safely assume that basic regurgitation is not what they meant by writing, which, if true, makes the above objection something of a nonsequitur.
    bgun · 1790818695 · focus · HN ↗
    Your point seems to reduce to “bad writing=bad thinking, better writing=better thinking” which to me seems to support the original point, not refute it.
    ModernMech · 1790851842 · focus · HN ↗
    I’m not going to elevate memeing to thinking, no. If that’s the bar then using ai is just as much thinking as writing and the whole “writing is thinking” meme is pointless.
    customguy · 1790860056 · focus · HN ↗
    What is "memeing" in this context? From what I can see, it's just someone claiming something "seems" like a meme to them because it's repeated a lot. Is the idea that getting enough sleep is healthy also a "meme"? That Alzheimer and cancer suck and have no upsides? What's the actual criticism here, feeling left behind on an insight many other people already attained?
    bunderbunder · 1790869966 · focus · HN ↗
    I'm reminded of that Hitchens quip about interpreting ad hominem arguments as a tacit concession that you've made a good point. If they had a more substantive rebuttal then they would have led with that instead.
    The memeing accusation wasn't technically an ad hominem, but it does at least live on that side of town.
    ModernMech · 1790877789 · focus · HN ↗
    > What's the actual criticism here
    I stated this in an earlier post: "Probably what matters more is the specific process."
    > Is the idea that getting enough sleep is healthy also a "meme"?
    Yes actually.
    > That Alzheimer and cancer suck and have no upsides?
    Maybe? I don't think that qualifies, It's more like an emotional response to a disease.
    > What is "memeing" in this context?
    Repeating memes. In this case "writing is thinking" is a meme in the culturally transmitted idea sense. I don't think it qualifies as thinking because it's just the mechanical propagation of those memes through the culture. So if we're going to classify that and all other stuff one writes down as thought and elevate it, I don't see why prompting an AI isn't among that.
    customguy · 1790880846 · focus · HN ↗
    And how do memes get propagated "mechanically"? People say things like "the sky is blue" or that cancer sucks because they happen to agree, not because they heard it and just repeat whatever they heard all the time. Accusing someone of parroting something, instead of actually meaning it, is such a cop-out.
    I mean sure, "writing is thinking" is shortening something, like "sharing is caring" does. Of course different things are not the same things. But it's not something people just "repeat", and when you ask them why they say it, they can't give you anything. Maybe that's why you're neither asking (why they say that, what they mean etc.) nor telling (in what way you disagree, what you think instead etc.).
    > So if we're going to classify that and all other stuff one writes down as thought and elevate it, I don't see why prompting an AI isn't among that.
    (IMO) of course it is, who said otherwise? Just the output isn't.
    JambalayaJimbo · 1790860776 · focus · HN ↗
    [dead]
  2. 1718627440 · 1790798920 · focus · HN ↗
    Recalling, recategorizing and expressing is still thinking?
  3. customguy · 1790859706 · focus · HN ↗
    The insight that writing helps to reflect on and structure thoughts is as old as it is trivially obvious.
    > If people cannot write well, they cannot think well, and if they cannot think well, others will do their thinking for them.
    - George Orwell
    customguy · 1790881441 · focus · HN ↗
    Turns out he never said that, sorry: <a href="https://quotle.info/who-said/if-people-cannot-write-well-they-cannot-think-well/" rel="nofollow">https://quotle.info/who-said/if-people-cannot-write-well-the...
    I still think there is some truth in it, just but it could be expressed less crudely and less arrogantly. For me trying to think honestly is way more important than how "sophisticated" it is.
3. bunderbunder · 1790802270 · focus · HN ↗
  I returned to doing a lot of my own coding for this reason.
  I don't mind farming out the more monotonous bits to AI. When I was letting an agent handle the whole implementation for me, though, I found that I was rediscovering all the pitfalls of waterfall-style development. Because I was doing waterfall-style development. I was trying to pin down all the details in a plan document up front, which is inevitably the point in time where I know the absolute least about the best way to accomplish the task. And then I let the agent do the rest for me, which undermines my opportunity to learn and understand more.
  The result was continual accumulation of bad decisions and unnecessary technical debt. The only difference between now and back in the bad old days of 20 years ago is this time instead of being the put-upon code monkey I had become the boneheaded engineering manager who isn't paying attention to the code and doesn't realize what a brittle mess it's become.
4. gexla · 1790825451 · focus · HN ↗
  This also gives you some surface area for LLMs to help you out in writing rather than code. Have it give an adversarial response or whatever you think is important. Then you can also see what is obviously wrong with the LLM's argument along with some nuance or interesting points you may have missed. Then you can have it pull in upstream sources of knowledge done on the topic, which is something that has been game changing revealing at times for me. "Here's the text from which all else flows, it was written 60 years ago, notice that nothing on this list has been written in the last 20 years." You know you got a keeper when that happens.
arialdomartini · 1790794137 · focus · HN ↗
On top of this, it pays off to write the commit messages before the code
<a href="https://arialdomartini.github.io/pre-emptive-commit-comments" rel="nofollow">https://arialdomartini.github.io/pre-emptive-commit-comments
1. drdaeman · 1790794754 · focus · HN ↗
  Jujutsu is perfect for that - you create new changeset upfront, providing message at the same time (which can be later amended as needed). Feels so much more logical to declare the topic first, rather than come back to some accidentally uncommitted changes and wonder what was doing there.
  1. xixixao · 1790795376 · focus · HN ↗
    "Topic" is usually covered by branch name. Commit message goes with a set of code changes, it feels more logical to me for the message to describe the actual code as it was written (as it might have changed from the idea phase).
    sbuttgereit · 1790796052 · focus · HN ↗
    [delayed]
    SAI_Peregrinus · 1790800476 · focus · HN ↗
    Also branch names are extremely limited in what they can describe.
  2. TeMPOraL · 1790797485 · focus · HN ↗
    Agreed. You can preplan a bunch of small steps and then fill in changes.
  3. arialdomartini · 1790797905 · focus · HN ↗
    Exactly! For anyone interested, I guess the previous comment refers to the Squash Workflow, which happens to be very idiomatic in Jujutsu
    <a href="https://arialdo.codeberg.page/ju-ju-tsu/tutorial/moving/squash-workflow.html" rel="nofollow">https://arialdo.codeberg.page/ju-ju-tsu/tutorial/moving/squa...
  4. 1718627440 · 1790798999 · focus · HN ↗
    You can start to write the commit message first in Git too. (And I do that.)
2. Sarkie · 1790795494 · focus · HN ↗
  BDD. Absolutely changed my world
  1. Garlef · 1790797540 · focus · HN ↗
    As in gherkin/cucumber? Or more generally?
    (the language... I, for the love of it, can't remember which is which)
3. tommica · 1790796073 · focus · HN ↗
  On hindsight that should be obvious! Pre-write your commit message, because of course you know what you are going to work on!
kayashaolu2 · 1790796339 · focus · HN ↗
[dead]
einpoklum · 1790796448 · focus · HN ↗
> Now we are in the era of agentic coding, where everything from code to commit descriptions is written by AI.
No, we are not. Sure, there is a lot of slop-coding/vibe-coding going on, but not much of it in serious code. In my experience and to my knowledge.
Of course, I encounter the opposite problem with humans: They often don't bother to write proper commit messages; and many tend to squash them in favor of giant single-commits which just say "Implemented feature #123".
cerved · 1790796573 · focus · HN ↗
Claude tends to just narrate the change when it writes the commit message. Which is not very interesting. Anyone can read the diff and figure out _what_ it does. The interesting is why.
So I've been instructing Claude to commit like Jeff King.
At first, Claude would mainly just cosplay Peff. Emulate the prose and not the process. Over the last few months I've been iterating on it and now Claude writes vastly better commit message than by default.
Initially, Claude would produce A LOT of plausible sounding reasons the LLM "thought" made sense. Instruct an LLM to give reason and it'll give you reasons -- whether they are real or not. After trying to instruct it not to lie, make shit up etc (which did not work) I instead started forcing it to articulate the source of the rationales. Especially which claims where unsubstantiated, and this seems to have helped a lot.
Then I instructed it to do some thorough investigation before it commits.
Start by writing a brief that gathers different "evidence" that underpins a change. The diff itself. The surrounding context. A bit short git log. A blame on the touched lines to see what previous commits touched this code and for what reasons.
Once it's done the agent has to tag each claim according to a category. I.e. what claims are attributed to the change itself (the diff), the inciting incident (gathered from session or if missing, by follow-up questions), what's inferred by the model (unsubstantiated claims.)
Only after this supersize is it tasked with writing a commit message given this brief. Or to ask follow-up questions if there's only unsubstantiated claims or gaps in the brief. Furthermore, it is tasked with writing a note to detail assumptions it has made and, or other relevant bits of information that are not commit message worthy, but possibly still interested in noting down. Decisions made. Options not taken. Possible rationales for the change that didn't make the cut.
All of this tends to make pretty good commit messages. Not perfect, but a good starting point.
Right now my biggest challenge is finding instructions to write the Goldilocks message. Not too brief and not too long. Instruct it to be clear and concise and relevant information gets left out. Say nothing and get a Dostoevsky novel. At least when it writes too long messages it's easy enough to go in afterwards with a `git history reword` and take out the axe.
One of the biggest upsides has been, just as when you read a human that writes commit messages like this, is spotting misunderstandings. Several times I've spotted gaps in the reasoning of the message that doesn't match reality, and caught mistakes. A bit like when you use plan mode.
1. fg137 · 1790802035 · focus · HN ↗
  Claude has been so bad that I find it easier to hand write commit messages and PR description. It works much better than nudging Claude to write things down in a readable and meaningful way.
  1. cerved · 1790836506 · focus · HN ↗
    The latest batch of models have noticeably improved. But Opus 5.1 was peak claudeish
JaumeGar · 1790797088 · focus · HN ↗
[dead]
evnp · 1790798425 · focus · HN ↗
> When the AI doesn’t know the ‘why’ part, it comes up with its own reasoning. I find that dangerous. When we read that later, it may not make sense, because the real reason was completely different.
Even more dangerous: when the text _does_ make sense, despite being detached from reality.
1. fphilipe · 1790803138 · focus · HN ↗
  I have this rule in my global AGENTS.md:
  > When writing a commit message, briefly explain at a high level what was done (the details are in the code). Explain the why of the commit; if you don't know that, ask me.
  It works quite well. When it doesn't have it in context, it does ask.
ajuc · 1790799105 · focus · HN ↗
[delayed]
dkarl · 1790799683 · focus · HN ↗
I was forced to give up on commit messages long before AI, because other people were so bad at them that I happily agreed that all PRs should squash commits.
At least then the squashed messages were usually pretty decent. But then people started using AI (or AI started using people) to create absolutely massive commit messages that are impossible to skim in git blame and overall very bad for human consumption.
AI has made massive strides in virtually every other way. Why do they continue to write in a wasteful, human-hostile way?
I think we'd have to be be very naive not to suspect that this is intentional. AI companies have a stated goal of replacing humans in the software development process, and they're actively making the process itself inhospitable for humans.
They are injecting massive amounts of text into their customers' development process, which becomes tokens that their customers will then pay them to process over and over again.
1. luipugs · 1790807908 · focus · HN ↗
  I suspect there's a prompt one can add to improve the consumption of commit messages for humans, just that the default one is pretty bad. Kind of similar to the AI generated posters a few weeks back: <a href="https://news.ycombinator.com/item?id=49764791">https://news.ycombinator.com/item?id=49764791.
flopsamjetsam · 1790800253 · focus · HN ↗
I sometimes use the AI prompt to do a similar thing: I'm struggling with a problem, or putting my ideas down in a coherent manner, so I write a prompt, and in doing so the idea crystallises for me. I've tried doing this just in a text editor, but there's something about having the next action be "submit this to X" that clicks my brain into higher gear.
I suppose it's very similar to drafting a letter or an email to someone.
jamietanna · 1790800661 · focus · HN ↗
I'm resisting linking to several posts I've written on these lines before - I very much agree that - at least personally - writing the commit message helps me work through what's changed and most importantly why.
When AI writes the code for me, I then end up still writing the commit message so I can take ownership of the change myself, make sure I can explain why the change was made and see if there's any missing context that may lead to a different result
pnt12 · 1790803836 · focus · HN ↗
I agree with the article, but I like to write, while lots of people just see it as a chore.
To people who don't like to write a ticket or PR description, the AI text is better than nothing.
kecupochren · 1790832099 · focus · HN ↗
I go even further and ask Claude to generate code with 0 comments. I then read the code and add them myself. It forces me to decrypt all the weird looking code and understand it. The comments only land on things that actually need them
dishantsethi · 1790845450 · focus · HN ↗
[dead]
fowlhowl · 1790850648 · focus · HN ↗
Completely agree with this! I have been forcing myself to write the comments myself. And this friction, is what lets me remember the things that went in , and create a mental map of the changes in the system.
1. Otterly99 · 1790861890 · focus · HN ↗
  That is also the workflow I settled on with agentic AI.
  First, I have very small implementation steps and each represent a commit. Second, I write the commits myself because it forces me to read the implementation and understand it.
_superposition_ · 1790866929 · focus · HN ↗
I do something very similar but I use the pr description, as I always squash my commits per pr. Keep em small I say, agent or not.

Open on Hacker News to reply ↗

Unofficial Hacker News client; not affiliated with Y Combinator.