Git Commit Messages#


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:

  • searchable

  • informational

  • clean

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 chanell at (I am still active in IRC) and we were talking about the importance of proper commit messages when this happened (real nicks ommitted):

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.

beyond that, it's up to the development team to implement

yeah, teams should decide what they want to do

People who do not understand and/or read about git and this kind of stuff
dislike even attempting to get good at it.

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...

if proper commit messages have no purpose other than being proper commit
messages.. they're a waste of time

user_0: which problem are you actually trying to solve?

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

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 ←

There is a Git repo where the contents of .gitattributes file is
"* java eol=lf" ... is that correct?

→ nobody answers, the same person insists ←

perhaps the line should be "*.java eol=lf" instead of "* java eol=lf"?

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_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_3: it's an attribute that someone made up

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_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

maybe the commit message has a clue

Good idea. Do a git log -S java -- .gitattributes

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_3: And no extra description on the commit?

user_0, was a big commit... looks like they applied some auto
style formatting

I guess it's a typo. I'm just saying it's technically legal the way it

user_2: here's an example where proper commit message and usage of the
tool would be invaluable

I will print this conversation. It may help my future arguments with

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 spotless”. They seem to have changed the .gitattributes file with some strange stuff (or it was a type, 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.