Is the full set of possible headers and their ordering in a git commit documented anywhere?

The documentation of git-commit-tree states the following:

A commit encapsulates:
     all parent object ids
     author name, email and date
     committer name and email and the commit time.

However, the presence of the the -S flag and observed commits in the wild include a gpgsig header, which is not mentioned in the list above.

Moreover, the documentation implies that commits may also include an encoding header although I have yet to see one in the wild.

Commit objects created with the above setting record the value of i18n.commitEncoding in their encoding header. This is to help other people who look at them later. Lack of this header implies that the commit log message is encoded in UTF-8.

The Pretty Formats documentation lists information that can be extracted from a commit, but it does not make any claims about whether that information is exhaustive.

Is the full list of possible headers and valid values documented anywhere?

Or is it unsafe to write code that makes assumptions about the set of possible headers?

Solution

Is the full list of possible headers and valid values documented anywhere?

That's going to be the source. commit.c shows "gpgsig-sha256" and "mergetag" are additional possibilities; I've seen mergetag in I think it was linux commits.

It is very definitely unsafe to write code that thinks it knows all possible header entries. New ones can be added as needs arise, that got the three mentioned above, I forget when but not all that long ago.

The header format follows a time-honored convention: it ends with a pair of newlines; each entry starts with a nonblank-first character, that first word is the entry name, any additional lines with leading blanks are concatenated as if they'd been wordwrapped (which they have) and the result is the entry value.

Everything following the newline pair is the message itself. It is safe to expect new header entries to follow this convention. I'd feel confident enough to hardcode an expectation of that format and that the first entries will always be tree, any parents, author, committer, in that order.