4 ms·

The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more

The problem is that usually we don't write the WHY in the commits... We tend to always capture the WHAT in the form of prose. And for agents, this is just more noise, since all they need is just the diff to reconstruct the WHAT. I've never seen someone write decisions or the intent they started with in commit messages. Even the solutions today that auto-generate commit messages just summarise the diff. This was helpful when humans were the only ones reading the history. But for agents its useless.

skydhash 7mo ago
> I've never seen someone write decisions or the intent they started with in commit messages You may not have seen enough good repos. The following is an example commit from freebsd https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f9037b47b2b164d4c1bebd09 https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f903... A proper email is like an email. You have the first line as the subject and it may be enough to explain the intent of the diff. But sometimes it’s not enough and you add more details in the body. I strongly believe that people who write the WHAT again don’t know that there’s a diff attached to the commit and think of them a separatete objects. GitHub and VSCode do not really help in that regard.
- vidimitrov 7mo ago
  This looks very good. Thanks for sharing. I can only imagine how much discipline it takes to write these kinds of commits manually.
  - skydhash 7mo ago
    Is it discipline? When you think of the patch as an unit of idea and the commit as the means to convey that idea, it takes the same amount of effort to write an email message. BTW you do not have to write those for every single commit. You can always rebase interactively and create a final set of commits for sharing. No one cares about what’s in your local copy of the repo.
  - keybored 7mo ago
    You don’t have to look far to find it. Git and Linux, the two first Git-based projects, work like this. You could have found this if you did just a little research before declaring an open standard.
- svstoyanovv 7mo ago
  I think this requires discipline. The good thing is that we have coding agents, but again, you need a standard to tell the agent what to always look for, how to find it, and to describe your modules properly (even Claude Opus 4.6 makes mistakes when doing hops when tracing code spanning files). Btw, there is also a paper on this issue, Google released it recently
- codethief 7mo ago
  > The following is an example commit from freebsd The Linux kernel is another great example. Random commit from yesterday: https://github.com/torvalds/linux/commit/d56b5d163458c45ab8fa1f00bd875af01b3ce28c https://github.com/torvalds/linux/commit/d56b5d163458c45ab8f...
- no-name-here 7mo ago
  Obviously projects have their own standards around comments, but as the why is apparently important and non-obvious, would it be even better for the ‘why’ to be a code comment in order to understand why code exists without looking through the git history for each line?
- keybored 7mo ago
  > A proper email is like an email. A proper commit message is like an email?
0x457 7mo ago
Because commit history is here to explain WHAT and not WHY. "Why" is explained by a decision log such as ADR which can be store in the same repo and can be mutated in the same commit that has WHAT in its commit body. But also, if you look at large projects like Linux or FreeBSD, commits there explain why as well.
- agateau 7mo ago
  I disagree with this: commit messages should explain the Why. For the What, I can read the diff. Sadly, many commit messages are about the What.
- teeray 7mo ago
  > Because commit history is here to explain WHAT and not WHY. When that commit gets implicated by `git bisect` and all you see in the message is exactly what you’d see by reading the patch anyway, you’ll wish the author answered why they did what they did. This, especially, when the author is no longer at the company.
az09mugen 7mo ago
The WHY in the commit should just be a ticket ID or reference, at the beginning of the commit. And IMHO in the first place the code is meant to be for humans, not machines/programs. Rhetorical question : If the LLMs are so great, why don't they just generate bytecode for binaries directly ?

skydhash 7mo ago

> I've never seen someone write decisions or the intent they started with in commit messages You may not have seen enough good repos. The following is an example commit from freebsd https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f9037b47b2b164d4c1bebd09 https://cgit.freebsd.org/src/commit/?id=ac5ff2813027c385f903... A proper email is like an email. You have the first line as the subject and it may be enough to explain the intent of the diff. But sometimes it’s not enough and you add more details in the body. I strongly believe that people who write the WHAT again don’t know that there’s a diff attached to the commit and think of them a separatete objects. GitHub and VSCode do not really help in that regard.

vidimitrov 7mo ago
This looks very good. Thanks for sharing. I can only imagine how much discipline it takes to write these kinds of commits manually.
- skydhash 7mo ago
  Is it discipline? When you think of the patch as an unit of idea and the commit as the means to convey that idea, it takes the same amount of effort to write an email message. BTW you do not have to write those for every single commit. You can always rebase interactively and create a final set of commits for sharing. No one cares about what’s in your local copy of the repo.
- keybored 7mo ago
  You don’t have to look far to find it. Git and Linux, the two first Git-based projects, work like this. You could have found this if you did just a little research before declaring an open standard.
svstoyanovv 7mo ago
I think this requires discipline. The good thing is that we have coding agents, but again, you need a standard to tell the agent what to always look for, how to find it, and to describe your modules properly (even Claude Opus 4.6 makes mistakes when doing hops when tracing code spanning files). Btw, there is also a paper on this issue, Google released it recently
codethief 7mo ago
> The following is an example commit from freebsd The Linux kernel is another great example. Random commit from yesterday: https://github.com/torvalds/linux/commit/d56b5d163458c45ab8fa1f00bd875af01b3ce28c https://github.com/torvalds/linux/commit/d56b5d163458c45ab8f...
no-name-here 7mo ago
Obviously projects have their own standards around comments, but as the why is apparently important and non-obvious, would it be even better for the ‘why’ to be a code comment in order to understand why code exists without looking through the git history for each line?
keybored 7mo ago
> A proper email is like an email. A proper commit message is like an email?

0x457 7mo ago

Because commit history is here to explain WHAT and not WHY. "Why" is explained by a decision log such as ADR which can be store in the same repo and can be mutated in the same commit that has WHAT in its commit body. But also, if you look at large projects like Linux or FreeBSD, commits there explain why as well.

agateau 7mo ago
I disagree with this: commit messages should explain the Why. For the What, I can read the diff. Sadly, many commit messages are about the What.
teeray 7mo ago
> Because commit history is here to explain WHAT and not WHY. When that commit gets implicated by `git bisect` and all you see in the message is exactly what you’d see by reading the patch anyway, you’ll wish the author answered why they did what they did. This, especially, when the author is no longer at the company.

az09mugen 7mo ago

The WHY in the commit should just be a ticket ID or reference, at the beginning of the commit. And IMHO in the first place the code is meant to be for humans, not machines/programs. Rhetorical question : If the LLMs are so great, why don't they just generate bytecode for binaries directly ?