-
Notifications
You must be signed in to change notification settings - Fork 227
Git Commit Style Guide
This wiki page is to set a few recommended guidelines for making Git commits such that they are clear and useful for later developers. Commit messages can be seen as the primary way of documenting software development.
A commit message can be composed of a title (required) and a body (optional).
The title is defined by the first line in the commit message, and serves as a summary of the commit. It should ideally be less than 72 characters. This title is displayed when viewing commits on GitHub and in various other command line operations (e.g. interactive rebasing). Guidelines to keep in mind:
- Use sentence case, but do not add a period at the end
- Use imperative mood (e.g. "Fix ABC" or "Add XYZ")
- Be specific, e.g. say "Fix incorrect use of foobar in Class.method" instead of "fixed variable"
An empty line (i.e. two line breaks) separates the title from the body of the commit message. The body does not have a length limit, although it is recommended to add hard line breaks at ~72 characters to improve readability from the command line or git clients which don't have wrap text. Guidelines to keep in mind:
- Use sentence case
- Use bullet points if helpful
- Describe why the change was made
- If there was a problem, describe the problem and how the change fixes it
- Describe any limitations of what was implemented
The following is an example of a good commit message (output from git log):
commit f7f1fee7d05085b0dd2104a36e60ffef7788d792
Author: alongd <alongd@mit.edu>
Date: Wed Jul 12 11:34:02 2017 -0400
Removed logging.debug message in reaction.py __setDegeneracy()
Due to the numerous calls to __setDegeneracy(), this debug message
appears repeatedly while debuging (or running tests with -d). In fact,
it could get printed so many times that it fills the CMD stack.
When rendered in Github, this commit looks nice because of good separation of title and body.
The easiest way to make a git commit is to use the -m/--message argument, e.g.
$ git commit -m 'This is the commit message'
The supplied message will then become the commit title. To supply a commit body, you can use additional -m arguments:
$ git commit -m 'This is the commit title' -m 'This is the commit body'
However, writing the message in an editor (via normal git commit) or gui may be easier.
It is also possible to fix a commit message after the fact. If the commit you would like to fix the the most recent commit, simply do git commit --amend. If it isn't, then you can reword it via an interactive rebase. The specifics of rebasing are out of the scope of this page, but you can read more in the git documentation or other guides.
After certain git operations such as squash, git will auto-generate messages for you. Usually that is not ideal. Rewriting a concise and updated message is always recommended.