Git Commit Messages

Bryan Lott published on
2 min, 330 words

git commit -m "gah!"

So, apparently, git commit messages are a point of contention with developers. Yeah, the ~50 characters you get to say what the commit does, your state of mind, why this is a thing, etc. Not only that, this is the message that's probably lost when you squash merge your commit. Maybe it's just me, but I find very little value in reading any git commits. There's just not enough context without reading the associated code, and if you're doing that... the commit message probably won't provide you that much extra information.

That being said, two things I have started using commits for is:

  1. A summary of the work done in the commit. Sometimes this is nothing more than "gah!" or "try to unbork things". I know, not great messages, but they're all I can stomach at the moment when I'm in the midst of trying to get a piece of code to do the thing I want it to do.
  2. An answer to the question "What happens if I merge this commit?" These are where the good commits usually are. Things along the lines of "Add glue:* permissions to Spark worker". Tells you exactly what happens if you merge the commit.

Here's the thing, to provide enough of a summary so that the person coming behind you (likely to be you when you've lost the context you currently have) in ~50 characters is HARD, like, getting-threading-locks-right-hard. So, if you give me commit messages like "terribleness", "joy", etc, I'll probably just laugh and go read the code. If you've given me one of the commit messages that gives me enough context, I'll still go read the code since all documentation is suspect, especially mine!

Good git commit messages are bonus points, nothing more. So to get up in arms about it feels, silly, and possibly a sign of bikeshedding. Write good ones if you can and don't criticise those that can't.