How To Write Better Commit Messages For Version Control

Writing concise, yet descriptive commit messages for version control is a difficult art to perfect. While you’re on the path of getting those notes down to their efficient best, here are a few questions to ask yourself before doing that push.

3. How informative and readable is my message?

As the saying goes, put yourself in the other person’s shoes. If you’re going through a dense series of commits, the last thing you want to see is:

Fixed some stuff

That’s an extreme example, but certainly not rare. At the very least, prefix your note with an acronym or term that relates to what the commit affects:

[Database] Fixed incorrect SQL statement in first load


2. Will my message be truncated or altered somehow?

GitHub is a good example of where this is the case. Check out the list of Mono project commits in the lead image. As you can see, many of the messages are truncated. While it’s impossible to write notes for larger commits that go under this limit, you can work around it by:

  • Making many small commits, rather than a few large ones
  • Try to use keywords — method and module names, for example. Anything that can get the point across in as few words as possible

1. How can I format a large commit message?

OK, so it’s the worst case scenario — you’ve had to overhaul a major system that’s touched multiple files and there’s no way you can get around making a massive commit. How do you break it down so everyone won’t hate you?

Obviously, this comes down to taste, but here’s one approach I’ve seen that works:

Check generic instantions for constraint violations.

    * class.c (mono_class_init): Check instantiations of generic instances.

    * icall.c (ves_icall_Type_MakeGenericType): Ditto.

    * verify.c: Add mono_verifier_class_is_valid_generic_instantiation to the 
      internal API so generic instances can be checked.

    Fixes #654136

It’s direct, covers all the affected files (and methods) and gives the reader a good enough guide when they dive into the commit itself.

Have any of your own tips for writing commit messages?

The Cheapest NBN 50 Plans

Here are the cheapest plans available for Australia’s most popular NBN speed tier.

At Lifehacker, we independently select and write about stuff we love and think you'll like too. We have affiliate and advertising partnerships, which means we may collect a share of sales or other compensation from the links on this page. BTW – prices are accurate and items in stock at the time of posting.


2 responses to “How To Write Better Commit Messages For Version Control”