Skip to content

Git commit messages: Why or what?

 Published on 9th May 2022

I’ve always been told that when writing a git commit message, it should explain the why rather that the what behind the changes. The reasoning is that a reviewer can see what you have done by looking at the code, but they have no context as to why. My thoughts on this are that it should explain the what, especially if you work with pull requests.

There are two situations that I am most likely to be looking at a commit message. The first is when I am reviewing code and the second is when I am searching the history of a project to find a specific commit.

In the first instance I don’t care too much about the commit message because if I am reviewing code, I am doing that from a pull request. At my current job my team has a template for pull requests where we list what we have done, instructions for how to QA the changes, and a link to the GitHub issue, which should provide the context needed for the review.

In the second instance I am looking for a specific change. Maybe that’s when a feature launched or when a bug was fixed. Either way, having a list of what has changed is invaluable to me rather than trying to figure out which commit I need by the context given.

I will say that I have never seen a consistent commit style in any codebase that I have ever worked on, and generally the messages have a tendency to lean closer to the what side of the coin as opposed to the why, so perhaps this is a moot point?