Tech Thoughts

Git the subject right

Communication is an important skill for programmers, but this usually doesn't show in commit messages like “fix bug”. This post will show you how to write good commit messages.

Most programmers agree that communication is an important skill. Yet, many write commit messages like "fix bug" or "add thing".

Using git bisect to detect which commit introduced a bug is a frustrating experience if it ends with a commit message like "Fix 2". Similarly, git blame loses its usefulness as a tool for understanding if the commits aren't explanatory.

Good commit messages have a short, one-line subject, optionally followed by a blank line and a more detailed description.

The description can contain anything that helps a reader who's doing code review, or who's trying to understand the history. Context, concerns, and alternative solutions can all be mentioned here. Of course for small changes the subject is often enough, but always consider whether a description would be helpful.

Here's an example of a good commit from the go project:

    commit 8ec7a39fec2acab98ce5e41363dd1c65c03d7479
    Author: Ian Lance Taylor <[email protected]>
    Date:   Fri Jun 16 09:29:44 2017 -0700

        os/signal: avoid race between Stop and receiving on channel

        When Stop is called on a channel, wait until all signals have been
        delivered to the channel before returning.

        Use atomic operations in sigqueue to communicate more reliably between
        the os/signal goroutine and the signal handler.

        Fixes #14571

The subject summarizes the changes, and even provides some context by mentioning the os/signal package, while the description explains in more detail what was done and references the issue at the end.

Messages like these make a git history more pleasant to work with, and help by sharing knowledge. Additionally, writing them trains you to communicate your thoughts. So consider spending a bit more time on commit messages, and regard them as an exercise for clear communication.