Commit description as a thinking tool
yedhu.me
yedhu.me
And I’ll just say, after this exercise I can definitely concur that writing exposes gaps in your thinking very fast. Especially when you’re trying to explain your point to someone who is new to the topic.
"Writing is nature's way of letting you know how sloppy your thinking is."
The memeing accusation wasn't technically an ad hominem, but it does at least live on that side of town.
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.
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.
> If people cannot write well, they cannot think well, and if they cannot think well, others will do their thinking for them.
- George Orwell
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.
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.
Tangent: I once worried about things breaking when commit messages got too long. I tried really long commit messages and nothing broke: https://github.com/kccqzy/long-commit-messages/commit/ccfda4...
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.
Also, due to HN comments not being the best with formatting this kind of thing, I kept these lines very short. It's the gist that matters most.
I don't know where I picked up this style, but it was before I ever got hired anywhere. It was common across several places I worked at later on in the 2010s. I strongly prefer this to rambling prose. The first line is the Jira ticket description, by the way.
MYPRJ-73: Auth bug redirect loop
- Frontend router fixes
- Check cookies before redirect
- Default redirect to login page
- New case added for "expired"
- Backend
- Update repurposed Apache config
- Remove old DBM
- Update cookie response header
- Don't use "SameSite=Strict"
- Removed 3rd-party lib
- We own this code for nowhttps://arialdomartini.github.io/pre-emptive-commit-comments
Branches for example aren't named in Jujutsu. You can bookmark them which gives them a name in some sense... but that's an optional thing you can do, often as a concession to centralized Git interoperability.
So in this case the parent to your post isn't thinking about it wrong given the context and such workflows have their advantages I've found.
https://arialdo.codeberg.page/ju-ju-tsu/tutorial/moving/squa...
(the language... I, for the love of it, can't remember which is which)
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 then becomes tokens that their customers will then pay them to process over and over again. It's like a CO2 scrubber that emits CO2.
Even more dangerous: when the text _does_ make sense, despite being detached from reality.
> 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.
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.
I guess the main advantages of Git history are that it’s (1) uneditable and (2) directly linked to a specific commit.
That's why I prefer to keep any important information as close as possible, either in the commit message or as a comment in the source code, to make sure it's unmissable to anyone working on it later.
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.
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
I did find that distilling some of my style choices to a `commit-style` skill helps when an AI writes a commit message (for me to rewrite) to be not quite as generic, but it's still needing my ownership to get it right
I suppose it's very similar to drafting a letter or an email to someone.
I'll ask AI to write integration between 3 services, and it'll write the class names from the service A in comments in service B and C if I'm not careful.
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.
Happy to read good reasoning why it's fucking blow-up.
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.
I believe they can do this due to having millions of public pull requests and github issues in their training data.
* 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.
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.
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".
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.
To people who don't like to write a ticket or PR description, the AI text is better than nothing.
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.