Commit Messages¶
Introduction¶
Commit messages matter. One of the goals of any repository is to keep the project’s history in good shape.
The main goals of following agreed upon (good) practices on a given project’s repository amounts to these:
Organized.
Clean.
Searchable.
Informational.
Those three characteristics form a symbiosis that leads to traceability, which in turn helps pinpointing the cause of problems when things go wrong (and they do go wrong).
One lamentable episode¶
Once upon a time, I was in the #git IRC channel at libera.chat (I am still active in IRC) and we were talking about the importance of proper commit messages when this happened (real nicks omitted):
user_0
Are there "official" git documentation on writing proper commit messages?
What I see is people random opinions in posts all over the web (some very
sensible, true). I have had little success educating people on writing an
informative and concise subject line followed (when appropriate) by some
explanation for the reason of that commit.
user_1
beyond that, it's up to the development team to implement
user_2
yeah, teams should decide what they want to do
user_0
People who do not understand and/or read about git and this kind of stuff
dislike even attempting to get good at it.
user_0
It is hard to explain, argue and have an educated conversation about a
subject with people who do not know about that subject. “Ignorance more
frequently begets confidence than does knowledge.” I see that all the
time. I hope I myself don't do it as much as I seem to watch other people
doing it...
user_2
if proper commit messages have no purpose other than being proper commit
messages.. they're a waste of time
user_2
user_0: which problem are you actually trying to solve?
user_0
user_2: I am trying to convince people that commit messages matter. That
keeping a repo organized, clean, informational, semantic, etc. helps. Helps
troubleshooting problems, finding historical stuff, and makes everyone
happier. user_2: Then commit messages could be like "first commit", "second
commit".
user_0
Sure. I add to that that just because you are linking to a ticketing
system doesn't relive people for being responsible in writing good code
and commit subject and description in general.
→ Then someone asks this question ←
user_3
There is a Git repo where the contents of .gitattributes file is
"* java eol=lf" ... is that correct?
→ nobody answers, the same person insists ←
user_3
perhaps the line should be "*.java eol=lf" instead of "* java eol=lf"?
user_4
user_3: I think attributes can be free-form (ie. there's no finite
list of legal attributes). So in theory it looks like it sets the "java"
attribute on all files
user_3: try git check-attr -a some/file
yep. man gitattributes "DEFINING MACRO ATTRIBUTES"
user_3
user_4, is "java" even a real attribute? I'm reading the documentation for
gitattributes and it seems maybe "java" can be a "built-in pattern", but
not an attribute
user_4
user_3: it's an attribute that someone made up
user_4
But whatever that attribute does, it sure sounds weird to put in on all
files. So I would still guess it's a typo
user_3
user_4, okay... I think one of two fixes will work. Either remove the
asterisk and let "java" be the first thing on the line which makes it
the built-in pattern... or putting a dot between * and java which makes
"*.java" the pattern
user_4
maybe the commit message has a clue
user_0
Good idea. Do a git log -S java -- .gitattributes
user_3
user_0, yeah, I saw where they added it. It was on a commit
called "spotless applied" whatever that is... I'm not a Java person
user_0
user_3: And no extra description on the commit?
user_3´
user_0, was a big commit... looks like they applied some auto
style formatting
user_4
I guess it's a typo. I'm just saying it's technically legal the way it
is.
user_5
user_2: here's an example where proper commit message and usage of the
tool would be invaluable
user_0
I will print this conversation. It may help my future arguments with
people.
user_2
user_5: you don't need to convince me
TL;DR: Someone was struggling understanding something in the repository, and there had been a massive commit with lots of files which went through some tool to format them, and the only thing the commit message said was “spotless applied”.
But they did more than “apply the spotless thing.”
They had changed the .gitattributes file with some strange stuff (or it was a typo, god knows) and nothing in the commit message to give a clue.
I’ll refrain myself from showing here a few other scenarios that I have been through at work lest I get in trouble with my current or previous employers.
The list of situations like this goes on.
Read the Chris Beans post (linked below) and the others as well.
TODO: We intend to add our own examples where regarding commit messages, atomic commits, squashing commits (when it makes sense, not all the time), etc.