Anatomie eines git Commit-Kommentars

Everyone using git as version control system will sooner or later figure out how a git-commit comment should look like. For all readers who didn’t yet figure it out, I’ll explain it in an example:

Short description, max. 80 chars

Optional longer text describing the commit. It is allowed to be multiline and
should explain the reason for the commit.

Optional signatures.

You might now ask: Why is it done like this? Let’s take a real world example to discover the reason:

mesa: remove '(void) k' lines

Serves no purpose as the k parameter is used later in the code.

This commit removed several lines of code. If the author would have omitted a comment, you would be wondering why he did that. Lucky for us git enforces commit messages. In many cases the first line of the comment isn’t really precise, but rather follows the pattern of “stating the obvious”. It helps to find a commit, but it does not necessarly explain the reason. This only becomes obvious from the following lines.

Signatures

Git allows the user to add signatures to a commit message, e.g.:

Signed-off-by: Christoph Brill <webmaster@egore911.de>

These signatures carry additional information about the people involved with the commit. There is no real standard for these signatures, but the following are proven to be useful in several projects:

  • Signed-off-by: The commit was added by the signer to the repository. It is meant (more or less) as specifying an additional author
  • Reviewed-by: The commit was read by the signer and got positive feedback
  • Tested-by: The signer applied the commit locally and tested it

Everyday usage

In a perfect world everyone would be writing detailed comments (within the sourcecode as well as in commit messages). But reality show, that this is not necessarly the case. Even in very disciplined projects some commits will fail this ideal criteria. Git (and many other version control systems) allows using simply structured commit messages to better understand the commit (for other developers as well as the author at a later point), without reading all the code lines of a commit.

Copyright © christophbrill.de, 2002-2018.