The Why: A Better Git Commit Message

The Why: A Better Git Commit Message

Dariusz Pasciak

October 31, 2016

I was recently tasked with fixing a third-party integration issue that started occurring suddenly and with no apparent reason. The source of the problem was an iframe on a page that was misbehaving.

My first hunch was to git blame the line of code that had the iframe to see when the last changed occurred and what that change was. The diff was very simple:

- <iframe src="https://fake-3rd-party.com/widget?code=12345" />
+ <iframe src="https://fake-3rd-party.com/embed/WXYZ" />

Nothing cryptic there. It hinted that something may have changed with the integration and that was causing the issue. I went to look at the commit message to get some more info, and that read as follows:

Author: Some Guy <some.guy@some.domain>

 changed iframe src

Wow. That was very helpful. Thanks, Some Guy.

The story doesn't end here, but my point begins here.

When we're writing a message for our next commit, let's take a moment to consider whether the message is at all informative. Is there anything else that we could include with the message to provide a liiitle more context into what's going on? A link? Anything?

If we're really stumped and just can't think of how to make the commit message useful, let's start by asking ourselves, "Why am I making this change?" Answering that question will at least reveal the motivation for the change, which, in and of itself, can be pretty informative. At minimum, it can serve as a starting point for further investigation.

Let's incorporate that "why" into our commit message and move on.