Personally I strongly prefer adding a prefix to all my commit messages. Usually it’s a small form namespace on what you are touching. This could be the library or module name.
This allows easy filtering of relevant commits and gives you a quick overview of relevant changes you are interested inn. You could also use conventional commits, but personally I don’t like them.
Yeah, I think that makes sense for large projects and monorepos.
My feeling on prefixes and conventional commits is that people should do it if they find value in it, but they should do it thoughtfully and recognize the costs. I think for conventional commits especially, people adopt them without recognizing that it adds a burden for contributors to learn the project’s particular prefix rules, and it eats up scarce screen real estate in the commit title.
I think it’s probably worth including a link to conventional commits ideas in the doc and present some arguments for and against. Personally I prefer not to use them in smaller projects, but I maintain a larger rust crate where we’ve chosen to use them and find that they’re generally useful. In particular, having a convention for when commits have breaking changes helps us automate that side of things in our changelogs.
My reasons for preferring not to use them come pretty much from the idea that they often artificially constrain the language in ways that tend to promote bad commit summaries in ways mentioned in your doc. E.g. fix: background color bug instead of “Change background to pink to fix color contrast’.
I originally did have a section on Conventional Commits and other style choices, but I felt like style discussion was bloating the scope of the article, so I trimmed it out.
I favor it, but the extremely-short 50-character “limit” on the first line of the commit means that sometimes it has to go. If I did something to the TimestampedCircularBuffer type I’ve already blown half of my first-line budget. If I also add metricutil: to the head of the line that would leave me with 12 characters to say what I actually did.
I believe the 50-character limit is fake. It is stated in man pages for git, but neither git, nor kernel follow it! Someone should send a PR removing in from manpages.
Do you know software that actually requires the 50 character limit? I also see it highlighted in vim, but ignore it if my message has to be longer to be meaningful (I’d say I stay below 80 all the time, but go above 50 quite often). So far no problems. I think also git log displays the full line.
Nothing really requires it, but it looks bad in GitHub for example if you ignore it, and my editor forces a line break unless I try hard to override it.
A question about commit messages: what do people here feel about repos that enforce a rule of (almost always and only) single-line commit messages?
I ask because I’ve run into this rule more than once when contributing to open source projects. I’m used to it by now, but I was frankly confused the first time someone said “Why did you include a whole paragraph after the commit message?” (To be fair, they also seemed confused that I had included what seemed like a novel to them in my commit message.)
I’m tempted to file it under the “how to not use Git” category. Somewhere close to the projects that demand contributors to push subsequent revisions and feedback actions in follow-up commits of the PR (aka git commit -m "Fix stuff" and git commit -m "Fix stuff again"), never rebase, never squash, and end up with a polluted, non-bisectable, non-making-sense history that serves no higher purpose other than “this git thing gets in the way of writing code”.
nononono. A one-line commit message might be appropriate if it’s “import the vendor list for 2025-03” or “add a missing comma”, but if the actual change required any significant amount of thought then the commit message should be equally thoughtful. Anywhere between two sentences and most of a page is appropriate. Any longer, and you should probably writing a document somewhere else, and including a link and a summary in the commit (and possibly in the code).
Here’s a fairly typical message of mine (reflowed for your reading pleasure):
supervisor: remove empty slices from the qState.tokens map
When returning tokens, if there are no more tokens, remove the slice from the tokens map instead of leaving an empty slice in place. Otherwise, qStates will accumulate map entries for all of the queues they have ever had tokens for, which may be substantial. Profiles show a lot of time spent in mapiter2 called from qState.mdvalue, so this should help with that.
Sounds really weird. At first I thought “Single line commit rule? He must mean repositories forbid single line commits?”
As a junior developer I also wrote commits with only the single line often. And I still do in hobby projects where I might commit once per week. But the commit text is so helpful when the repository grows older. Want to find out why somebody changed that line of code 3 years ago? The reason is not in the code (it might in a comment), but if you’re lucky and the guy wrote a good commit message, then it’s in the commit message.
The more difficult a bug / problem is to solve, the longer my commit messages get to explain what the problem was and why it’s fixed in the way I did it.
In a remote-only role my commit messages usually also are a good wrap-up of all the considerations that went into making this commit as is (and thus might answer some questions the reviewer has already).
I do not remember a project that forbid longer commit messages. Sometimes the requirement is that the first line should be meaningful and concise (then you can add an empty line and more text). Often the rule is that the commit message must start with a ticket number (a change request or a bug report).
That sounds like a bad idea, as you can’t explain every kind of commit in a single line.
You’ve encountered this more than once?
I feel like the problem maintainers have is that contributors typically write terrible, meaningless commit messages, so the maintainers are usually trying to get people to elaborate more in their commit messages.
Yes. I’ve also seen plenty of repos where single-line commits are the norm—and where the exception is maybe a sentence or two. Maybe I’m hanging out in the wrong software circles.
This is highly dependent on culture of the team and style of development.
If you have an issue tracking system where you manage all bugs and change requests, then most information is here and discussions also happens here and then in commit message you can just link the number of the ticket (and maybe add some low-level comment for other developers, but it is optional, because everything important is already in the issue tracking system).
If the development is more spontaneous and informal and issue tracking system is missing or a lot of development work is done without assignments and formal change requests and bug reports, then commit messages are more important and deserve better description of what has been done and why.
If you have an issue tracking system where you manage all bugs and change requests, then most information is here and discussions also happens here and then in commit message you can just link the number of the ticket (and maybe add some low-level comment for other developers, but it is optional, because everything important is already in the issue tracking system).
And now you have an N+1 Select problem in your VCS. Now any time someone wants to understand the history of why a particular part of the code base changed in a certain way they have to do a mental manual join of each commit to each issue in the tracker. You’ve optimized for the current developers over the future ones.
I think the article should probably go deeper on why this is a problem, because it is one I’ve seen numerous times in legacy software maintenance.
An analogy for this is that an issue tracker is a plan for battle drawn up before any fighting starts, but a commit history is the journal of the what actually happened written by those who did the fighting. A history written for the survivors with just the first part is no real history at all.
I agree that the history is important and this is how I use the VCS – if I find some weird code and wonder why it was written this way and whether it was an intention or a weaker moment of the developer, I check the history and related tickets in the tracking system with comments from consultants or even customers and find the reasons behind it.
Whether these information should be duplicated in VCS is bit questionable – maybe as a backup case of issue tracking system loss… it probably will not harm anybody and will not take too much time to write such commit message. Important is that the details and motivation is documented somewhere.
I worked in a place where the issue tracker was full of really useful context, and I had the same process as you — always check the related tickets, because that would almost explain so much more of the context and reasoning for the change than any commit message could. The issue tracker had discussions with stakeholders, developers describing the issues they’d run into, all sorts of planning documents and diagrams, etc. So it had the plan of how changes would be made, the history of how they were made, and sometimes even retrospective/evaluation comments about what needed to be changed later.
Unfortunately, every other issue tracker I’ve used was anaemic in comparison, and so I’ve come to appreciate the power of a good commit message a lot more since working elsewhere.
I would write it in the commit message anyway. Yes, we have an issue tracking system, and branches are named after the ticket number, so you can definitely get some context just by looking at the merge commit, but bytes are cheap and having the information in-context is valuable. Also the commit messages can hold more developer-oriented technical information, while the issue tracker is more for the benefit of people who don’t actually care about most of that.
Personally I strongly prefer adding a prefix to all my commit messages. Usually it’s a small form namespace on what you are touching. This could be the library or module name.
Example from my own projects: https://github.com/Foxboron/ssh-tpm-agent/commits/master/
This is also commonly done in the kernel tree as well: https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/
This allows easy filtering of relevant commits and gives you a quick overview of relevant changes you are interested inn. You could also use conventional commits, but personally I don’t like them.
Yeah, I think that makes sense for large projects and monorepos.
My feeling on prefixes and conventional commits is that people should do it if they find value in it, but they should do it thoughtfully and recognize the costs. I think for conventional commits especially, people adopt them without recognizing that it adds a burden for contributors to learn the project’s particular prefix rules, and it eats up scarce screen real estate in the commit title.
I think it’s probably worth including a link to conventional commits ideas in the doc and present some arguments for and against. Personally I prefer not to use them in smaller projects, but I maintain a larger rust crate where we’ve chosen to use them and find that they’re generally useful. In particular, having a convention for when commits have breaking changes helps us automate that side of things in our changelogs.
My reasons for preferring not to use them come pretty much from the idea that they often artificially constrain the language in ways that tend to promote bad commit summaries in ways mentioned in your doc. E.g.
fix: background color buginstead of “Change background to pink to fix color contrast’.Thanks for reading!
I originally did have a section on Conventional Commits and other style choices, but I felt like style discussion was bloating the scope of the article, so I trimmed it out.
For fun, here’s what I had:
I use conventional commits for work, but for personal projects I don’t and I never though why, it was an unintentional decision.
I guess it’s because it’s more work, there’s no clear line between e.g. fix and refactor, it reads less natural for no apparent gain for me.
And I hate repeating the word “fix” twice.
I favor it, but the extremely-short 50-character “limit” on the first line of the commit means that sometimes it has to go. If I did something to the
TimestampedCircularBuffertype I’ve already blown half of my first-line budget. If I also addmetricutil:to the head of the line that would leave me with 12 characters to say what I actually did.I believe the 50-character limit is fake. It is stated in man pages for git, but neither git, nor kernel follow it! Someone should send a PR removing in from manpages.
Do you know software that actually requires the 50 character limit? I also see it highlighted in vim, but ignore it if my message has to be longer to be meaningful (I’d say I stay below 80 all the time, but go above 50 quite often). So far no problems. I think also
git logdisplays the full line.Nothing really requires it, but it looks bad in GitHub for example if you ignore it, and my editor forces a line break unless I try hard to override it.
A question about commit messages: what do people here feel about repos that enforce a rule of (almost always and only) single-line commit messages?
I ask because I’ve run into this rule more than once when contributing to open source projects. I’m used to it by now, but I was frankly confused the first time someone said “Why did you include a whole paragraph after the commit message?” (To be fair, they also seemed confused that I had included what seemed like a novel to them in my commit message.)
Sounds counterproductive.
I’m tempted to file it under the “how to not use Git” category. Somewhere close to the projects that demand contributors to push subsequent revisions and feedback actions in follow-up commits of the PR (aka
git commit -m "Fix stuff"andgit commit -m "Fix stuff again"), never rebase, never squash, and end up with a polluted, non-bisectable, non-making-sense history that serves no higher purpose other than “this git thing gets in the way of writing code”.nononono. A one-line commit message might be appropriate if it’s “import the vendor list for 2025-03” or “add a missing comma”, but if the actual change required any significant amount of thought then the commit message should be equally thoughtful. Anywhere between two sentences and most of a page is appropriate. Any longer, and you should probably writing a document somewhere else, and including a link and a summary in the commit (and possibly in the code).
Here’s a fairly typical message of mine (reflowed for your reading pleasure):
Sounds really weird. At first I thought “Single line commit rule? He must mean repositories forbid single line commits?”
As a junior developer I also wrote commits with only the single line often. And I still do in hobby projects where I might commit once per week. But the commit text is so helpful when the repository grows older. Want to find out why somebody changed that line of code 3 years ago? The reason is not in the code (it might in a comment), but if you’re lucky and the guy wrote a good commit message, then it’s in the commit message.
The more difficult a bug / problem is to solve, the longer my commit messages get to explain what the problem was and why it’s fixed in the way I did it.
In a remote-only role my commit messages usually also are a good wrap-up of all the considerations that went into making this commit as is (and thus might answer some questions the reviewer has already).
I do not remember a project that forbid longer commit messages. Sometimes the requirement is that the first line should be meaningful and concise (then you can add an empty line and more text). Often the rule is that the commit message must start with a ticket number (a change request or a bug report).
That sounds like a bad idea, as you can’t explain every kind of commit in a single line.
You’ve encountered this more than once?
I feel like the problem maintainers have is that contributors typically write terrible, meaningless commit messages, so the maintainers are usually trying to get people to elaborate more in their commit messages.
Yes. I’ve also seen plenty of repos where single-line commits are the norm—and where the exception is maybe a sentence or two. Maybe I’m hanging out in the wrong software circles.
This is highly dependent on culture of the team and style of development.
If you have an issue tracking system where you manage all bugs and change requests, then most information is here and discussions also happens here and then in commit message you can just link the number of the ticket (and maybe add some low-level comment for other developers, but it is optional, because everything important is already in the issue tracking system).
If the development is more spontaneous and informal and issue tracking system is missing or a lot of development work is done without assignments and formal change requests and bug reports, then commit messages are more important and deserve better description of what has been done and why.
And now you have an N+1 Select problem in your VCS. Now any time someone wants to understand the history of why a particular part of the code base changed in a certain way they have to do a mental manual join of each commit to each issue in the tracker. You’ve optimized for the current developers over the future ones.
I think the article should probably go deeper on why this is a problem, because it is one I’ve seen numerous times in legacy software maintenance.
An analogy for this is that an issue tracker is a plan for battle drawn up before any fighting starts, but a commit history is the journal of the what actually happened written by those who did the fighting. A history written for the survivors with just the first part is no real history at all.
I agree that the history is important and this is how I use the VCS – if I find some weird code and wonder why it was written this way and whether it was an intention or a weaker moment of the developer, I check the history and related tickets in the tracking system with comments from consultants or even customers and find the reasons behind it.
Whether these information should be duplicated in VCS is bit questionable – maybe as a backup case of issue tracking system loss… it probably will not harm anybody and will not take too much time to write such commit message. Important is that the details and motivation is documented somewhere.
I worked in a place where the issue tracker was full of really useful context, and I had the same process as you — always check the related tickets, because that would almost explain so much more of the context and reasoning for the change than any commit message could. The issue tracker had discussions with stakeholders, developers describing the issues they’d run into, all sorts of planning documents and diagrams, etc. So it had the plan of how changes would be made, the history of how they were made, and sometimes even retrospective/evaluation comments about what needed to be changed later.
Unfortunately, every other issue tracker I’ve used was anaemic in comparison, and so I’ve come to appreciate the power of a good commit message a lot more since working elsewhere.
I would write it in the commit message anyway. Yes, we have an issue tracking system, and branches are named after the ticket number, so you can definitely get some context just by looking at the merge commit, but bytes are cheap and having the information in-context is valuable. Also the commit messages can hold more developer-oriented technical information, while the issue tracker is more for the benefit of people who don’t actually care about most of that.