A Better Git Commit

I am a bad committer, there is no lying. Since learning Git in my final years of University, I managed to pick up a few bad habits, which have been with me ever since. When you do something everyday it’s easy to forget that there might be a better way.

Over the last few years the number of detailed commits I have made could be counted on one hand. Quite disgraceful really.

The desire to improve my commits really hit home after watching Zac Holman’s — More Git and GitHub Secrets Talk. Around the 15 minute mark he touches on some insights into the detail of the GitHub core commits. I can’t remember working on a project that comes anywhere close to this.

Everybody has terrible commit messages in some point in their life.

Sometimes every single day.

— Zac Holman

Making a better Git commit

Try to limit using the -m commit flag. git commit -m "A crappy commit message" and use git commit with no flags.

If using the simpler git commit command it should open up Vim (if it’s your default editor) where you can construct a better commit by following some of these simple steps.

  • The first line should be a short summary. Referencing the bug number or the main accomplishment of the change. e.g “Fixes issue #8976”. This is the title of your commit and should be less than 50 characters.
  • Then a line break.
  • Followed by a longer detailed description about the things that changed. This section is a really good place to explain what and why. You could cover statistics, performance wins, roadblocks, etc. The text should be wrapped at 72 characters.

Your commit should look something like this:

Clearly explain in one line what the commit is about

Describe the problem the commit solves. Justify why you chose
the particular solution. Reference the issue number if not
addressed in the title.

If you are new to Vim, I would highly recommend taking the time to spend 5 minutes to learn the basics. It is really not that bad. You can even learn in the terminal by running the vimtutor command.

Setting up Vim to help

To make things a little easy there are a few quick easy wins to be had with some small additions into your .vimrc file.

syntax on
plugin indenting on
autocmd Filetype gitcommit spell textwidth=72

This will cause Vim to have syntax highlighting on, wrap at 72 characters and turn spell checking on.

If you have any tips to help make better commits, please don’t hesitate to share below.

Happy committing!

8 thoughts on “A Better Git Commit”

  1. Great post Jake!

    I also have a bad habit of writing poor commit messages using the -m flag. The single line decription + detailed changelog and reasoning is a habit I think I’ll try to adopt.

  2. Nice post. One thing I do to remind myself to write a good commit message is to make use of Git’s templates. So as soon as I type `git commit`, Vim opens up with:

    Short summary

    + Why is this change necessary?
    + How does this change address the issue?
    + What side effects does this change have?

  3. I also highly recommend installing tpope’s vim-git plugin https://github.com/tpope/vim-git

    It includes syntax hl and some more modifications to make vim ready to handle multiple .git* files.
    F.e. it does highlight if your commit title is over 50 characters and also automatically wraps at the length you specified etc.
    Also supports .gitignore files and much more 🙂

  4. I added these settings to ~/.vimrc and now I get the following message:

    Error detected while processing /Users/****/.vimrc:
    line 2:
    E492: Not an editor command: plugin indenting on
    Press ENTER or type command to continue

Comments are closed.