Maybe I’m in the wrong, but commit messages have never been very useful for me in any situation. The amount of effort required to write excellent commit messages seems far too much for the returns it gives, at least in my experience (10+ years writing software with other people) I can only remember once where the commit message was at all useful to me and it was probably a 5 minute time-save.
Maybe if the commit messages were better they would have been more useful? Oftentimes I see context about the changes being spread out through several tools (Slack, GH issues, Jira, pull requests). If all of that was in the commit message, maybe it would have saved us much more time.
Also my experience, and why I improved my messages over time and appreciate when colleagues put in good error messages in turn.
good commit messages provide direct information when blame diving, and allow quickly discarding irrelevant commits
good commit explain the reasoning and edge cases of the original, and allow evaluating whether those choices hold, or whether the original author missed something, or whether I missed something (the latter being a reasonably common occurrence)
IME commit messages preserve a lot better across tool migrations because the commit message is just… there, you only need your ticket provider to fold, or someone to decide to stop paying for the old jira nobody uses anymore or decommission the old TRAC or Mantis server because “it’s useless” and you’re left bereft.
After 2 months of trying the approach outlined in this blogpost I must say I’m convinced now.
It hasn’t been that useful for others I believe, but it has been very useful for myself to sort the ideas of the patch and to review what makes sense in that patch and what doesn’t. And if someone ever has to go back to the patches I write they should have a better idea of what is going on. Both due to the improved messages and because of the patch cleanliness that comes from my increased awareness.
jujutsu has also been instrumental in making me write and rewrite commit messages a painless endeavour.
It could be, however I’ve worked with people that organized their commits very well and spent a good effort writing good commit messages and it wasn’t useful to me when dealing with their bugs anyway (it may be to them! or maybe they weren’t very good either). Just wanted to express my thoughts on something that I know is considered a good practice but that I’ve never found any value from.
I’ll try to apply some of what the post says to see if I change my mind tho.
In my experience if they spent that time writing more tests it would have been better (of course this is a bit of a false dichotomy, but if you have some time to do a task as it often happens in an office setting sometimes you need to choose what you spend your time in)
git bisect helps find the commit that does something particular. A good commit message then helps me understand why that commit did what it did. Were they considering the bug I’m chasing right now? Were they considering some other scenario that’s not in my head at the moment? Good commit messages can often automate away most of the Chesterton’s fence operation: figuring out what something does before you decide whether to modify it.
I prefer to encode the assumptions in a test or write it next to the code as a NOTE comment. The commit message just seems like the worst option, far away from the code that makes the assumption and depends on users reading the specific commit message that introduced it.
The single most valuable thing I’ve seen in commit messages is LLVM’s convention of NFC for things that are refactorings but should have no functionality change. When I see a bug in a commit with this tag, I know that the change in behaviour was an accident and not a side effect of some other (desired) change. That TLA alone has saved me a load of debugging time.
You can’t capture that in a comment because it makes no sense for an artefact in the comment to say ‘this behaves the same way it used to’ and because there often isn’t a single point in the source code to capture the lack of change.
Comments are by far the worst option as far as I’m concerned, people don’t care so they get lost, they drift away as new code is inserted, they don’t get updated when the code is, and there’s very much such a thing as commenting too much, whereas you can ramble on in commit messages as long as you organise and summarise them. Also commit messages work for changes which are spread out. Comments literally only work for spot information.
Rare comments are valuable, because they’re noticeable and denote something that’s so important it has to live next to the code.
I mean, yeah you can ramble as much as possible. I can also ramble as much as I want in a notion page or a markdown file in the /docs directory. Doesnt mean anyone will read it because it’s disconnected from the code people are reading. Unless you are just chasing a particular bug that was introduced in a particular commit and that assumption is encoded in the commit message (which already makes it harder since you also have to provide where the assumption happens and on which interfaces) noone will ever check those for a chesterton fence. I almost never write comments but when I make an assumption that is necessary I tend to write a // NOTE(Marce): We assume X Y Z. Noone has ever deleted one those in any codebase I’ve added them. I still prefer tests of course.
Tests, comments and commit messages all have their place.
Comments are good for recording the why of a system as a static thing. Some comments can be replaced by tests, but not all. Tests and comments work well together.
Commit messages are good for recording the why of a change. If you put the reason for each commit in code comments the comments would swamp the code.
The fact that commit messages are far from the code is precisely the point. I only want to see them when I’m interested in precisely why a line of code is written just so. As a bonus, the fact that they come with a timestamp gives me added context on how much to trust the documentation.
For me, git history / commit messages are only really useful on very large codebases. But by the time I need them at all, they are VERY useful. The biggest benefit is mostly scoping down the codebase to likely-relevant parts, or getting the perspective of “they were thinking about this” when they changed some struct that’s probably relied on in hundreds of different places with different concerns.
Small codebases simply don’t have the same organizational drift, half-done refactors, and countless pieces of public but untamed state. If you can’t hold the project in your head anymore, then having something that points to what parts the committer decided to hold in THEIR head can be invaluable. It’s good for figuring out what they didn’t think of, rather than identifying some bug sitting in the code that they actually committed.
The people who write good/reasonable commit messages don’t really need this
The people who don’t won’t really read a guide like this anyway
There’s a mythical person in between who does not write good commit messages, wants to get better and has the prerequisites to actually be able to get better for which guides like this may be useful.
I frequently benefit from my own commit messages for the purposes of identifying and fixing bugs, understanding the correct commit to revert, acting as a self-review of my code, and for clarifying my thoughts while I’m in the midst of building the commit (I’ve gone back and changed the content of my commit while writing the commit message). It’s absolutely beneficial to you - the writer - even if you’re the only person doing it.
i think they can be useful when they’re new, and the relevant context is still fresh in everyone’s head. you can glance at the recent commits, and see who is doing what, roughly. or the commits in a PR, to get someone’s thought process
once they’re ~a week old, i’d be fine if they were all git commit -m changes. and when i’m working solo, i just do that
if i’m searching through old commits, i’m always looking for something in the code, not something in the message
a further hot take here: if something would be useful in a commit message, it’s probably better as a code comment, and even better as a test or an assert
I’ve had the privilege to work with Simon and I will confirm his commit messages are by far and away the best I’ve seen. It’s been an invaluable learning resource to me to go through his commits comparing the commit message and the diff.
The last section I think is very important: you don’t have to do this every time. For every “good” commit message I do, I’ll do like ten “idk stuff” messages because they’re not likely to ever matter there.
When I have a 800 word commit message on a two line diff, that’s because the context of those two lines was a lot harder than it seemed.
This is an important detail of good commit messages. Unlike many practices, it’s still valuable if only you do it, or you only do it some of the time. Every good commit message you write is valuable in isolation. That’s a rare property for most processes!
I really enjoy discussing good commit practices. Based on my experience looking at the commits of other people I’ve worked with at the last 3 companies I’ve worked at, lots of people either don’t know how to organize good commits or they don’t see the value in it. I wish this wasn’t the case! Well-structured commits and thoughtful commit messages are a huge boon in the process of collaboratively building systems with code.
Something that can make the whole commit writing process a lot easier is a commit template file. You add the following lines to your git config file, create a file that matches the name with a template created, and then when you type git commit (without -m) it’ll open up your editor with a preformed template you can start filling in.
[commit]
template = ~/.gitmessage
Here’s the template I use if a usable example would be helpful.
Maybe I’m in the wrong, but commit messages have never been very useful for me in any situation. The amount of effort required to write excellent commit messages seems far too much for the returns it gives, at least in my experience (10+ years writing software with other people) I can only remember once where the commit message was at all useful to me and it was probably a 5 minute time-save.
Maybe if the commit messages were better they would have been more useful? Oftentimes I see context about the changes being spread out through several tools (Slack, GH issues, Jira, pull requests). If all of that was in the commit message, maybe it would have saved us much more time.
Also my experience, and why I improved my messages over time and appreciate when colleagues put in good error messages in turn.
After 2 months of trying the approach outlined in this blogpost I must say I’m convinced now. It hasn’t been that useful for others I believe, but it has been very useful for myself to sort the ideas of the patch and to review what makes sense in that patch and what doesn’t. And if someone ever has to go back to the patches I write they should have a better idea of what is going on. Both due to the improved messages and because of the patch cleanliness that comes from my increased awareness.
jujutsuhas also been instrumental in making me write and rewrite commit messages a painless endeavour.It could be, however I’ve worked with people that organized their commits very well and spent a good effort writing good commit messages and it wasn’t useful to me when dealing with their bugs anyway (it may be to them! or maybe they weren’t very good either). Just wanted to express my thoughts on something that I know is considered a good practice but that I’ve never found any value from.
I’ll try to apply some of what the post says to see if I change my mind tho.
In my experience if they spent that time writing more tests it would have been better (of course this is a bit of a false dichotomy, but if you have some time to do a task as it often happens in an office setting sometimes you need to choose what you spend your time in)
And I’ve found it useful to refer to commit messages for context (e.g. found from git blame) on multiple occasions 🤷♂️
Fair enough, just my experience. With git blame I usually find what I want without caring for commit messages and if not git bisect does the rest.
git bisecthelps find the commit that does something particular. A good commit message then helps me understand why that commit did what it did. Were they considering the bug I’m chasing right now? Were they considering some other scenario that’s not in my head at the moment? Good commit messages can often automate away most of the Chesterton’s fence operation: figuring out what something does before you decide whether to modify it.I prefer to encode the assumptions in a test or write it next to the code as a NOTE comment. The commit message just seems like the worst option, far away from the code that makes the assumption and depends on users reading the specific commit message that introduced it.
The single most valuable thing I’ve seen in commit messages is LLVM’s convention of NFC for things that are refactorings but should have no functionality change. When I see a bug in a commit with this tag, I know that the change in behaviour was an accident and not a side effect of some other (desired) change. That TLA alone has saved me a load of debugging time.
You can’t capture that in a comment because it makes no sense for an artefact in the comment to say ‘this behaves the same way it used to’ and because there often isn’t a single point in the source code to capture the lack of change.
Comments are by far the worst option as far as I’m concerned, people don’t care so they get lost, they drift away as new code is inserted, they don’t get updated when the code is, and there’s very much such a thing as commenting too much, whereas you can ramble on in commit messages as long as you organise and summarise them. Also commit messages work for changes which are spread out. Comments literally only work for spot information.
Rare comments are valuable, because they’re noticeable and denote something that’s so important it has to live next to the code.
I mean, yeah you can ramble as much as possible. I can also ramble as much as I want in a notion page or a markdown file in the /docs directory. Doesnt mean anyone will read it because it’s disconnected from the code people are reading. Unless you are just chasing a particular bug that was introduced in a particular commit and that assumption is encoded in the commit message (which already makes it harder since you also have to provide where the assumption happens and on which interfaces) noone will ever check those for a chesterton fence. I almost never write comments but when I make an assumption that is necessary I tend to write a // NOTE(Marce): We assume X Y Z. Noone has ever deleted one those in any codebase I’ve added them. I still prefer tests of course.
Tests, comments and commit messages all have their place.
Comments are good for recording the why of a system as a static thing. Some comments can be replaced by tests, but not all. Tests and comments work well together.
Commit messages are good for recording the why of a change. If you put the reason for each commit in code comments the comments would swamp the code.
The fact that commit messages are far from the code is precisely the point. I only want to see them when I’m interested in precisely why a line of code is written just so. As a bonus, the fact that they come with a timestamp gives me added context on how much to trust the documentation.
For me, git history / commit messages are only really useful on very large codebases. But by the time I need them at all, they are VERY useful. The biggest benefit is mostly scoping down the codebase to likely-relevant parts, or getting the perspective of “they were thinking about this” when they changed some struct that’s probably relied on in hundreds of different places with different concerns.
Small codebases simply don’t have the same organizational drift, half-done refactors, and countless pieces of public but untamed state. If you can’t hold the project in your head anymore, then having something that points to what parts the committer decided to hold in THEIR head can be invaluable. It’s good for figuring out what they didn’t think of, rather than identifying some bug sitting in the code that they actually committed.
I agree that this is mostly faff, because:
There’s a mythical person in between who does not write good commit messages, wants to get better and has the prerequisites to actually be able to get better for which guides like this may be useful.
I frequently benefit from my own commit messages for the purposes of identifying and fixing bugs, understanding the correct commit to revert, acting as a self-review of my code, and for clarifying my thoughts while I’m in the midst of building the commit (I’ve gone back and changed the content of my commit while writing the commit message). It’s absolutely beneficial to you - the writer - even if you’re the only person doing it.
i think they can be useful when they’re new, and the relevant context is still fresh in everyone’s head. you can glance at the recent commits, and see who is doing what, roughly. or the commits in a PR, to get someone’s thought process
once they’re ~a week old, i’d be fine if they were all
git commit -m changes. and when i’m working solo, i just do thatif i’m searching through old commits, i’m always looking for something in the code, not something in the message
a further hot take here: if something would be useful in a commit message, it’s probably better as a code comment, and even better as a test or an assert
yeah, this is my view as well, also completely agree on your last point! I think I mention it elsewhere in this comment section as well
I’ve had the privilege to work with Simon and I will confirm his commit messages are by far and away the best I’ve seen. It’s been an invaluable learning resource to me to go through his commits comparing the commit message and the diff.
The last section I think is very important: you don’t have to do this every time. For every “good” commit message I do, I’ll do like ten “idk stuff” messages because they’re not likely to ever matter there.
When I have a 800 word commit message on a two line diff, that’s because the context of those two lines was a lot harder than it seemed.
This is an important detail of good commit messages. Unlike many practices, it’s still valuable if only you do it, or you only do it some of the time. Every good commit message you write is valuable in isolation. That’s a rare property for most processes!
I really enjoy discussing good commit practices. Based on my experience looking at the commits of other people I’ve worked with at the last 3 companies I’ve worked at, lots of people either don’t know how to organize good commits or they don’t see the value in it. I wish this wasn’t the case! Well-structured commits and thoughtful commit messages are a huge boon in the process of collaboratively building systems with code.
Something that can make the whole commit writing process a lot easier is a commit template file. You add the following lines to your git config file, create a file that matches the name with a template created, and then when you type
git commit(without-m) it’ll open up your editor with a preformed template you can start filling in.Here’s the template I use if a usable example would be helpful.