Guidelines for Good Git Commit Messages
What is a commit message?
As you write, edit, and refactor your code, it can be hard to keep track of all these changes, what the changes are doing, and why you’re making these changes. A commit saves your changes to a local repository, and adding a clear message will help you keep track of those changes.
Why is it important to write good commit messages?
A good commit message communicates the context of a change to other developers and your future self. It not only tells you what changed, but why. Whether you’re working on a personal project, working with a team, or contributing to open source, it’s a good habit to keep. A useful revision history is important for productivity and efficiency in code maintainability over time.
What does a good commit look like?
A conventional commit follows the general guidelines listed below. Of course there are varying conventions used by different developers, teams, and companies that you will have to adapt in those environments.
Commit Convention Guidelines
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line and each paragraph
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
- Include the original problem, the code may not be self-explanatory
Short Summary (50 characters or less)
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 the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes 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 indentIf you use an issue tracker, put references to them at the bottom,
See also: #456, #789
How often should you git commit?
Commit as often as possible. In practice, committing a few times per hour is common. A good rule of thumb is committing after each new feature is completed (it works and doesn’t break anything), no matter how minor the feature might seem. If you fixed a typo, a bug fix, added a comment, anything relevant is worth committing. In case your edits start breaking things, if you’ve committed a clean working version, you have the security of reverting to that version! Plus, in the event that your computer crashes, all your hard work won’t be lost. For this reason alone, your future self will thank you.
How to Write Good Commit Messages: A Practical Git Guide
To create a useful revision history, teams should first agree on a commit message convention to use. This also applies…