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.
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.
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.
"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).
In Git, but workflows in Jujutsu aren't necessarily the same as in Git.
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.
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.
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.
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.
I like git-notes (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.
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.
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.
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?
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 commit message.
This makes no sense to me. The code is already self-documenting if written well, and all you need is a one line commit message to summarize that.
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.
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.
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!
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.
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.
Happy to read good reasoning why it's fucking blow-up.
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.
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.
> 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".
https://arialdomartini.github.io/pre-emptive-commit-comments
https://arialdo.codeberg.page/ju-ju-tsu/tutorial/moving/squa...
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.
(the language... I, for the love of it, can't remember which is which)
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.
I guess the main advantages of Git history are that it’s (1) uneditable and (2) directly linked to a specific commit.
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.
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.
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.
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.
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.
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".