Write Good Git Commits

Writing quality Git commits has been written about to death, but it is so important that I could not help myself from sharing my thoughts on the subject. Mostly, I will be rehashing what Tim Pope has shared, but I will also include a few of the things that I have used to improve my source histories.

Limit the subject of your commit to 50 characters

Many people live life as I do: at the command line. Limiting to 50 characters allows room for us to use an 80 character width for commands such as git rebase –interactive without width concerns. Even for those in a more modern IDE, the limit is important.

As commit messages get longer, it becomes more difficult for everyone to traverse your history.

Use the commit body for important details

It is very rare that I see people extend their commit histories into the body portion of a commit but it is the perfect place to offer extra details. Things like what resources you used to make a specific decision are better left in the commit history than in code comments most of the time. In a recent commit to my dotfiles, I added a quick alias to correct a TouchBar issue I was having.

Fix TouchBar when it (frequently) breaks

From http://osxdaily.com/2017/01/11/manually-refresh-touch-bar-mac/ this
will reset the control portion of the touch bar which has been
frequently breaking in New and Interesting Ways™.

Without these details, I might never be able to find the source for why I added this.

Also, limit the line length in the body to 72 characters.

Do not use the –message option

Pretty much everyone I watch make a commit will do so directly at their command prompt with git commit -m. Forcing yourself into an editor will encourage you to add additional details about a commit message. Additionally, your editor can configured to alert you to the 50/72 rule. Simply add au FileType gitcommit set t==72 to your vimrc to auto wrap git messages at 72 characters if vim is configured as your Git editor. vim-git is also a fantastic option that will highlight based on these rules.

If you are struggling with breaking your -m habit, try creating a bash function to prevent its usage.

function git {
  if [[ $@ == "commit -m" ]]; then
    echo "Do not specify -m for commit"
  else
    command git "$@"
  fi
}

Commit as if giving a command

How to Write a Git Commit Message made me consider the subject of my commits a little more. In bullet point 5, Chris says “Use the imperative mood in the subject line.” Considering Git itself follows this rule, it made perfect sense to jump on board.

Merge branch 'bugfix/correct-spacing'

And

Revert "Implement person CRUD"

The best advice I picked up was write your commit as if you are completing the following sentence: “If applied, this commit will…”

Rebase your branches, but leave master alone

Rebasing is a heated topic in the community but the one thing that everyone can agree on is leaving master alone. Once your commit has made it there, it is history and should never be changed. However, your branch is your story. You get to tell it however you want so craft it in a way that is useful to the reader.

For me, this is particularly important because the second thing I do when reviewing a new code base is look at the commit history to see to story of the application. Unfortunately, most are riddled with messages like “fixed typo” or “asdf” and the history becomes unreadable.

Take care in crafting your git messages and you will find much more value in your git logs!