Proper Git Commit Messages

Maybe it's a bit pedantic, but it really bugs me to see poor Git commit messages. We've all seen them, they run on to two or three lines or they're just a single lazy word like "fix". Maybe they just don't summarize the change coherently. Or they're just written in the impoper tense. Whatever the case, writing poor commit messages is doing you and your collegues a disservice.

The commit message is key to understanding the change the commit introduces. So, please let's all do each other a favor and embrace the preferred model for Git commit messages: a one line summary followed by an optional description.

Capitalized, short (70 chars or less) summary

More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.

Write your commit message in the present tense: "Fix bug" and not "Fixed bug." This convention matches up with commit messages generated by commands like git merge and git revert.

Further paragraphs come after blank lines.

  • Bullet points are okay, too
  • Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here
  • Use a hanging indent

Always use the Present Tense

  • Fix bug ... (not "Fixed bug" or "Fixes bug")
  • Add test .. (not "Added test" or "Adds test")
  • Refactor ... (not "Refactored" or "Refactors" or "Refactoring"
  • Upgrade to Spring 4.1.4-RELEASE .. (not "Upgrades" or "Upgraded")

Why the present tense? Because they describes what the commit does not what it did. Git commits should be written in the present tense because they happen multiple times.

They happen when you write them. They happen when you merge them into another branch. They happen when someone else pulls down those new commits to their repo. They happen when someone cherry-picks them onto their branch.

The Commit Subject

The subject line is clear, imperative, and short. Many Git tools and commands only show the subject of commits. So making them short and direct makes them much easier to follow.

Looking at a list of commits that only showed the subjects gives a clear idea of what this commit does.

The Commit Body

That subject line is supported by a detailed body that explains it even further. The subject tells us what the commits does, the body tells us why.

References

comments powered by Disqus

Software Engineer living in NYC
More Detail →
  • Software Engineering
  • Full Stack
  • Java
  • Spring
  • Linux
  • MongoDB
  • Objective-C
← Back

Recent Posts