CommitMessageConventions

From Git SCM Wiki
Jump to: navigation, search

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
Personal tools