Red Green Repeat Adventures of a Spec Driven Junkie

git: Always Write Good Commit Messages

I continue to share my “always do” series with git. The first two are at:

This one I discuss why you should always write a good commit message.

Bad Commit History

Conversely, what happens if you don’t write good commit messages? Well, the repository history starts to look like:

xkcd & git commit messages source and more information

  • Would you want to inherit this code base?
  • If you were trouble shooting an issue, would you know what commit to remove? How confident would you be in which commit?
    • How about when there’s a production issue Saturday night and everyone is out?
  • What impression do these messages give you about the people that contributed to this code base?
  • Are you confident in the contributors take their craft seriously?

Writing Good Commit Messages

Each team will have a different standard for a good git commit message. These are my recommendation for my team:

  • Always start with a topic:
    • FEATURE: this change is all new code
    • FIX: this fixes a problem
    • MAINTENANCE: this code change improves the code base (i.e. framework upgrade, security changes, etc.)
  • Have a top line summary why message after the topic, completing statement: “I made this change because…(insert answer to topic line)” - keep this to be less than 50 letters - with the topic!
    • Be creative with prose, it makes a difference!
  • Body of the commit should always have:
    • Expanded explanation of the topic
    • Link to any associate story ticket with this change (i.e. JIRA, Trello, issue number)
    • Explain why not what the code change is.
      • The code itself will explain what it is better than you ever can.

Even under pressure, spending five minutes to compose a good commit message will dramatically improve the code base.

Writing good commit messages takes practice as long lived code bases are a new phenomenon in software development.

Squash is Your Friend

Depending on your work style, if you like to make small commits before your final pull request, make them. Each commit message does not have to be fully fleshed out (although it will be good practice!)

Before making a pull request for your changes, squash all your commits together and write a fabulous commit message.

This will make your final submission of your work to your teammates even better and improve your craft as a software developer.

References

A great article that helped me improve my own commit message writing and understanding why:

Chris Beams - git commit

Want to see a code base with long history? Browse the Linux kernel commits:

Linux Kernel commit history