SOMH #1 - Ode to Verbose Commitment

This essay is part of the series "Strong Opinions, Moderately Held", an indefinite journey into thoughts, ideas, and convictions regarding a plethora of subjects.

Recently, Tekin Süleyman wrote an article on the some of the virtues of preferring git's verbose commit mode. I myself am a staunch supporter of this notion and, given the very nature of Twitter, gave it my full, succinct, and somewhat inflammatory endorsement.

Of course, this claim would remain just as unchallenged as 'never' means never, so I now intended to explain what I actually meant.

To me, the -m flag is nothing more than a quick, seductive path down the dark side of commit messages. It lends itself expertly to non-descriptive and nonsensical messages such as 'WIP', 'refactor', and 'fix test'. If you halfway through typing the commit message realise there's a taller tale to tell, there's no easy way of doing so. You've already committed to commit with a short message. In theory, you can turn back, but honestly, who would do such a thing?

If you on the other hand always default to committing using the -v flag, you have options. There's nothing stopping you from committing a short message, but you have the option to elaborate as needed. In addition, you will have a full diff of the staged changes listed right there in your editor. Do you tend to run git diff before committing? If so, getting into the habit of verbose committing will yield this automatically. This will have the added bonus of making it easier to formulate a good commit message. I can't count the number of times I've heard someone asking "so what did we do?" when issuing a git commit -m.

Options, flexibility, and pro memoria. To me, there's really nothing more to this than that. But, I ran into a surprising amount of pushback. Of course there are times when using the -m flag might be warranted.

My chief exception is when you diligently make frequent, incremental, tiny, atomic commits to a feature branch that then is squash-merged into the master branch. Typically, this entails committing every few minutes and it requires a level of focus and discipline that, at least in my experience, few can consistently muster. If I were to be contentious, I'd claim that it's kind of git's ”good” use of goto. It does happen, but far too seldom.

So, at the end of the day, it's my strong opinion, moderately held that you should avoid the -m flag in favour of the -v flag - or better yet, set the verbose mode to the default commit mode by issuing git config --global commit.verbose true.

That said, below are some actual counterpoints and my thoughts on them. If and as more views are raised, I'll expand this list.

"We mob program on separate computers and switch by committing and pushing WIP:s"

This is a duct tape solution to the real problem of not having a dedicated mob computer. If you for some reason truly cannot have one, then by all means, use the workarounds that are readily available to you. You've surely already noticed the detrimental effects of not having a dedicated mob computer so I need not unhelpfully pontificate that you really, really, really should get one.

"-v is great for context, but I prefer add -p for that purpose"

Cool, but this is completely orthogonal. What you commit and how you describe what you commit are two separate things. I love add -p myself and strongly advise using it when the discipline to commit has been too lax so that there are multiple, non-atomic uncommitted changes. But it has nothing to do with the way you formulate the commit message.

"I guess how to write and work with commit messages is the new tabs vs spaces"

To me, the tabs vs spaces debate is utterly arbitrary within the context of a coherent code base. Pick one or the other and stick to it. However, I don't consider the same to hold true for the way commit messages are crafted.