I don’t want to learn a DSL for my commit messages.
I think the commit message formatting becomes more relevant when you have hundreds of people working on a small set of files in the same repository. We did this with the administrative portal for Cisco Spark and found that having a standard format for people to follow means that there is less confusion and more summarization for each change that comes through.
I agree with @zg although I think it becomes relevant much earlier than having hundreds of people. Being able to parse and read the history of repository is more than a nice thing to have when working with other developers. When you even have 10 developers all doing their own thing and putting up long messages, some putting issues in the subject, some where the issue number is the subject with no body, it makes figuring out what happened and when that happened very very hard. While I might not like this particular format, standards like this aren’t about preference, it is about consistency and consideration for the other developers on the team.
My knee-jerk reaction to this article was, “Oh, I hate this.” Thank you for putting to words what my intuition was trying to tell me.
I’ve contributed to Karma several times, and it wasn’t really a lot of work. The project setup installs git hooks to check the commit message. It makes a lot of sense for maintainers as it is possible to generate a changelog.
The recommendations are pretty much what I would do anyway, except for the type/scope prefix.
This is a good template. I like how it looks and how it reads. I don’t know that I could sell any of my coworkers on writing it, but if it could be implemented as a commit template by default, it would be very nice.
That’s the problem. You really need some discipline, rebasing, and rules to make it work in a team or large project. Another thing that can help is a template or tool that sets the boilerplate up for you.
I find that using a git commit template can help with this w/out making things too complicated. Go to commit, fill out the template. Done. And at your discretion, just erase the template and write your own message, for example if you’re just doing a small fix that is self-explanatory.
We do something 20% of the way to this that’s been a big help. Due to popular demand I made a team-wide git pre-commit hook that only ensures commit messages begin with one of “ADD”, “UPDATE”, “REMOVE”, “DEVELOPMENT”, “BUGFIX”, “REFACTOR”, “CONFIG” or “DOCUMENTATION” in nice square brackets at the beginning of the commit message, and that the rest of the message is non-empty.
It’s made scanning through commit messages quite pleasant.
Most commit messages focus on the “what” of the commit, but I wish they focused more on the ‘why’. It’s nigh-impossible fit a ‘why’ into the first 80-character line, though, and it’s just so easy to stop writing a message after that line.
I always try to put the “why” in the long-form comment after the commit message. It takes some disciple and it’s not fun, but it’s always worth it.
Totally. I mean when you read a commit message “Removed therubyracer”, you can see the commit and be like “obviously, I can see that - but why? because I want to add it back in”.
If the “Why” is because you think it’s unused, that means it’s safe for me to re-add it (probably).
If the “Why” is because there was some critical flaw with using therubyracer and there is now some better way, then knowing that would help me tons so I don’t hit the same flaw.
I just picked therubyracer out of nowhere… well, recent history on a real project, but it’s totally arbitrary.
The same generally applies to comments in code. Most code comments that I come across are generally useless or too cryptic.
Simpler is better. Here’s what I use:
I reserve the last two ones for very important files (added or deleted). It’s certainly not perfect, but it works for me.
[Comment removed by author]
I just read it once and I think I’d be unlikely to need the glossary again.
My main problem with commit messages in git is typically that I find them inscrutable after a few months, or if it’s on a piece of code I’m not familiar with. My team has adopted a strategy of ensuring that commit messages have a motivation for the commit and then explain how it fixes the problem, which I really like, and you can find here. It’s quite lightweight.
Is there any other known template for commits? or another alternative for a verbose commit?
we adopted a slimmer version of this around 2 years ago for our internal codes at RhodeCode, once you start pushing on the format reading commits will never be the same, and we believe even for the team of just a few people benefits are big.
You see those after some time only, when you have to read lots of commits, when you do a code-review etc.