Writing useful commit messages for software version control

[Vagabond]

Hey everyone,

During a pair programming session with Hooman a while back, we briefly discussed commit messages. Basically I was writing everything in past tense when it is more appropriate to stick to the present tense.

I work regularly in Mercurial (HG), and my Git work is more recent just for Outpost Universe purposes. I was using Subversion (SVN) a fair amount for Outpost Universe work, although that may lessen now that we are looking at GitHub.

Anyways, besides switching to present tense for the subject of the commit message, I was wondering what other best practices there are, especially if they can be applied across different types of version control.

One of the top Google hits was by a programmer named Chris Beams. https://chris.beams.io/posts/git-commit/. I've never heard of him before but Google made it a top hit and his writing is easy to follow.

From his article:

The seven rules of a great Git commit message
Keep in mind: This has all been said before.
 * Separate subject from body with a blank line
 * Limit the subject line to 50 characters
 * Capitalize the subject line
 * Do not end the subject line with a period
 * Use the imperative mood in the subject line
 * Wrap the body at 72 characters
 * Use the body to explain what and why vs. how

I'm going to try improving my commit messages by following these suggestions. I'm not actually sure some of them matter for HG, like wrapping at 72 characters. (I typically use TortoiseHg and TortoiseGit, which both are nice enough to automatically wrap text).

If someone in the community has a differening set of best practices they typically follow for commit messages, I would be interested in reading up on it.

-Brett

[Hooman]

That was a good read. Thank you for posting that.

I think those rules are a good set to follow. That's roughly what I follow.

I don't make any special attempt to wrap body text at 72 characters, though I think the default editor mode might do that for me. I think it's mostly relevant in a terminal window, where the default width is 80 characters. Some commands might display a column of text alongside the message, so that makes room for it. Though no matter which way you go, there is going to be a case where things are likely to wrap funny.

[leeor_net]

I'm still unsure about manually wrapping lines, that sounds like a cludge for CLI dinosaurs, but the rest is perfectly sensible. I currently do something along those lines in my commit messages via Git.

[Hooman]

CLI dinosaurs

Hah! Yes. And even in a terminal, you can still wrap text to 72 characters if you used the same logic as a graphical text editor.

Though for Linux, the terminal is still alive and kicking. Especially for remote administration tasks. Having terminal commands also makes it really easy to script tasks. It's still the fastest, easiest, and most reliable way to do many things. But yeah, super old foundation.

I'd say not manually wrapping text allows for a more sensible path forward. You can write sensible algorithms to wrap text after the fact. Trying to unwrap text not so much. There may have been a valid reason for a line break other than just to wrap text at a certain number of characters. So yeah, I prefer not manually wrapping text.