HACKER Q&A
📣 csnover

Should commit summaries describe the change, or the intent?


I recently received some advice that the summary line of a Git commit message should describe what the change does. In particular, they said to avoid summaries in the form of “Fix ”.

For example, instead of “Fix wrong default font for FooComponent on BarPlatform”, write “Explicitly inherit BazComponent font for FooComponent on BarPlatform”. Or instead of “Optimise FooFunction memory use to improve performance”, write “Reuse existing heap allocations on BarObject in FooFunction”.

On the one hand, I can see that writing summaries this other way communicates more specific detail about what changed; “Fix ” could mean anything happened. On the other hand, what the change does is already described by the code, so focusing the summary on why the change was made instead seems much more beneficial.

This is probably more of a ‘spaces versus tabs’ kind of thing where the answer doesn’t matter too much, but I am curious to hear from others on which approach you have found most beneficial in your work. In particular, if anyone uses this style of “describe the change” summarisation, have you experienced any particular benefits that might not be obvious? Thanks!

  👤 naruhodo Accepted Answer ✓
> Should commit summaries describe the change, or the intent?

Yes.

Intent first, then a high level summary of the changes (if non-trivial).

Some programmers say that the code is the documentation and that comments in code are a "code smell". I strongly disagree.

The code is a communication between the programmer and the compiler, and leaves out intent. The code does what it does, right or wrong. But what we care about is what we intended the code to do, and why.

So intent is more important because the code could be wrong.

👤 stevage
I guess it depends on the context in which you are seeing the message.

For me, the most likely context is through blame or similar - I am looking at some code, and trying to understand its history. I see who changed it, when - and their commit message. In which case, only the intent is useful - I already likely know what the change does.

The "what it does" form is more useful if for some reason you're scanning commits trying to find the one that introduced some particular change. But that's not a use case I ever encounter.

👤 fragmede
All of it. It's a brain dump of where you are when you did the thing. Three years from now, you're going to want it to figure out what you're thinking when you wrote that bit of code. Future you is going to appreciate it. And then add in doing that for other people that come across your code as well.
👤 imron
This will improve your commit messages:

https://cbea.ms/git-commit/

👤 bediger4000
Intent. You can always get diffs of one commit vs another. You can't always discern why those changes happened
👤 tsujp
The changes should be the main meat of most commit messages and if the intent or other options considered add value to that then they should be included below.

The reality is if the intent, other options, relevant notes etc are not valuable then they will be lost to time (no loss). If they are valuable where else are you going to put them? Some wiki or knowledge store for your project? How will you know that this specific commit and that (probably) sparse text in said knowledge store are related? Why not just put them together where they belong anyway.

Commit messages are not valuable when they are maximally short. They are valuable when they describe the changes the commit applies and ANY other relevant information for people (including the author(s)) in the future so that said people can understand the commits effect and other relevant information.

For an example of amazing commit messages look at PostgreSQL’s. They are sometimes long with the changes, notes, intent etc and sometimes short.

👤 Xen9
The commits should describe your current mood diary-style.

git commit -m "procaffeinating."

git commit -m "fixed the bug that made me question my life"

git commit -m "Felt cute, might delete later"

git commit -m "embracing insomnia ..."

👤 sneed_chucker
Individual git commits often get squashed so I typically don't put much thought into them.

Pull requests, on the other hand, have an explanation/justification for the change and a summary of changes.

👤 BinRoo
My workflow is to create a pull request containing all the commits, squashed. So the title of the PR is really what matters, but then again, the PR itself contains great metadata, like the description, and the link to Linear, or whatever task planning tool.
👤 marginalia_nu
I don't think there is a should in this that doesn't, if you dig a bit, eventually boil down to personal preference. Hume's law and all that.
👤 chooma
Check out https://www.conventionalcommits.org
👤 msh
Just pipe in https://whatthecommit.com