CommitMessageConventions
OBSOLETE CONTENT
This wiki has been archived and the content is no longer updated. Please visit git-scm.com/doc for up-to-date documentation.
At the lowest level of git that defines the object format, a commit object consists of structural header in fixed format, followed by any binary blob you feed git-commit-tree from the standard input. I do not recall the details of the implementation offhand, but we _might_ chomp at the first NUL and if we did so I may say it is a bug -- commit-tree should not care what "the log message" part consists of.
It is however quite a different story when it comes to the higher level tools that come with git. The log summarization facilities to let humans interact with the commits expect that a commit log message consists of a one-line "summary", a blank line, and then the body of the message. These "log listers" are:
- git log --pretty=oneline
- gitk
- gitweb
- gitview
- git shortlog
The "one-line summary plus body of the message" has a strong correlation with how we communicate patches via e-mail. You do not start a sentence on the "Subject: " header and continue on to the body of the message, starting the body halfway of the sentence. Instead, you try to make sure you write something sensible by itself on the "Subject: " header to help the recipient when later scanning for it among bunch of messages, and you write a full paragraph that you can understand without reading the subject line first. The following commands that deal with e-mailed patches expect you to follow that convention:
- git am
- git applymbox
- git format-patch
Reference: http://article.gmane.org/gmane.comp.version-control.git/21987 email in the git mailing list
Trailers
Some projects or tools require informations in a header-like format at the end of commit messages.
Trailer | Project/Tool | Semantic |
---|---|---|
Acked-by: | Linux Kernel | Owner of the affected code said "yep, looks good to me" |
Bug: $NUMBER | Mediawiki Guidelines | References a bug in the Mediawiki Bugzilla installation |
CC: $PERSON <$MAIL> | Linux Kernel | Person has been informed about the patch |
Change-Id: $HASH | Gerrit | unique identification of a change that persists rebasing and amending |
Closes: $BUGNUMBER | git-buildpackage | Closes a bug |
Closes-Bug: $BUGNUMBER | openstack | like Closes: |
Co-Authored-By: | openstack | |
DocImpact | openstack | The commit changes documentation or needs documentation? |
Git-Dch: Ignore/Short/Full | git-buildpackage | Whether or not to include the short or full commit message in the generated changelog. |
Implements: blueprint $NAME | openstack | implements a feature described in the referenced blueprint |
Partial-Bug: $BUGNUMBER | git-buildpackage | like Closes:, but indicates that more work is still needed to close the bug |
Related-Bug: $BUGNUMBER | git-buildpackage | indicates a relationship to the referenced bug |
Reported-by: | Linux Kernel | |
Reviewed-by: | Linux Kernel | |
SecurityImpact | openstack | used to indicate that a change has security implications and should be reviewed by the OpenStack Security Group |
Signed-off-by: | Linux Kernel, git commit | |
Suggested-by: | Linux Kernel | |
Tested-by: | Linux Kernel | |
Thanks: msg | git-buildpackage | |
UpgradeImpact | openstack | used to indicate that a change has upgrade implications |