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

Better.

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?


Comments

    Seems a bit of overkill to name the individual files in the committed files in the commit message. That's like typing comments that say "the following code does this" when you can just read the code. Or a better example is that it's like typing out the contents of a folder before listing its contents.

    In the example commit you posted, it's very clear from the commit what was done and the first line more or less describes the changes. It just needs to be written better to be slightly more specific.

    Something like "Check generic instantiations for constraint violations and add mono_verifier_class_is_valid_generic_instantiation to the internal API - fixes #xyz"

    But then, probably even better to break it up into two commits. One to add the class, one to add the checks.

    Yeah, it comes down to personal style. But more commits are always better. But people are lazy so they just 'git add --a' and be done with it. But it doesn't take that much longer to type 'git add file1 file2 file3'.

    I find this a lot when working on Laravel projects. I end up working on controllers, views and requests in conjunction with each other and I end up with a whole bunch of changes. Go a step further and I'll have views and view partials, which I definitely want to commit separately.

    Yeah, it takes maybe a minute longer to write two or three commits versus one. But even then if there are chunks of the app that you know you're going to be regularly committing, you can just write a shell scrips. I have a few defaults like 'git-add-controllers', 'git-add-views' and 'git-add-partials' that check these areas of a Laravel application and stage changes.

    At the end of the day, if you get into the habit of hitting commit almost as often as you hit save, then you should be in good shape. And learn git commands.

    Unless they're fixing a broken build, rule of thumb for our commit messages in my team is that you put a one-line description of what you changed, then in parentheses put the bug ID for further info (no commits are made without an associated bug unless fixing a broken build) and the name of the code reviewer.

    Recently a few of the developers on my ream have gotten lazy and just put 'FIX ' which is really annoying because I have no idea from the commit message exactly what was changed unless I go look the bug up.

Join the discussion!