We focus a lot on writing high quality code, but commits are be overlooked, rushed as a single command done without thinking much about it. I know I’ve been guilty of it from time to time, especially on my own pet projects.

Let’s not do that, a commit in master lasts forever and having a cryptic message when one does git blame is just confusing and frustrating.

Don’t Dump Everything Into a Single Commit

This happens all the time, a commit lands with a decent commit message but it also has unrelated changes in it, most because the author of the commit just added everything that had changed into the commit with git add -a . after a long coding session turning the morning into night.

Instead of doing that, we can commit with

$ git commit -p

This goes through each change with a prompt to add, ignore, skip, et cetera all the chunks that have changed, doing it this way basically lets you review the changes as you add them to the commit, keeping it fresh in your memory what you are committing to the repository.

Never Lazily Write Commit Messages

Another common occurrence is commit messages written with git commit -m "Fix thing", you’re setting yourself up for failure doing this as there is no way you’ll be able to write a decent full page commit message using a single line prompt.

The goal of a commit message should be to accurately describe why the change was needed and what was done to make it happen, it’s okay to be verbose.

Write Well Formatted Commit Messages

Formatting is important too, the perfect commit message should have a capitalized short summary heading followed by the more detailed explanatory text.

Short capitalized summary, 50 characters or less.More detailed explanatory text, which should be wrapped at around 72 characters. If the message is not held within these limits it's not going to be readable anywhere.A subset of markdown like plain text formatting is fine, like lists and emphasis.

See also Tim Pope’s A Note About Git Commit Messages

Write Meaningful Commit Messages

The most useless commit message in my opinion is probably commits that read something like “Fix bug #15”.

Why is the change needed?

For your future self, as well as anyone reviewing a pull request containing the commit, answering this gives a bird-eyes overview of why the commit is even there.

How does it fix the issue?

A high level description of how the commit addresses the problem mentioned earlier.

Optimize collision detectionCollision detection was extremely slow and effectively unusable with more than 1000 objects due to it's lookup time being Introduce a spatial hash to optimize lookup time, reducing the algorithmic time for `collide_objects` from O(N) to O(1).

Projects have different policies on this but on projects I control, we don’t include links to issues etc in the commit itself, instead the pull request will contain the additional details that the

parser picks up, like cross references to issues and trigger keywords.

Let The Editor Help You

Exact steps depend on what your favorite editor is, and enumerating every single one wasn’t something I wanted to do here but set yourself up for success by letting your editor help you out, enable spell checking and set word wrapping to be 72 characters.