Re: extra headers in commit objects

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 3, 2010, 20:42 UTC
Message-ID: <7vwryugifz.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20100203192612.GD14799@spearce.org>

"Shawn O. Pearce" <spearce@spearce.org> writes:

> As I understand it, the current stance is:
>
> 1) A compliant Git implementation ignores any headers it doesn't
>    recognize that appear *after* the optional "encoding" header.

I first read the above to mean that you need to add encoding if you want to throw in other garbage.

I would say "*after* the mandatory 'tree', 'parent' (0 or more), 'author', and 'committer' headers that must appear in this order", for clarity.

Show 8 quoted lines

> 2) A compliant Git implementation does not produce any additional
>    headers in a commit object, because other implementations cannot
>    perform any machine based reasoning on them.
>
> 3) All implementations would (eventually) treat all headers equally,
>    that is they all understand what author, committer, encoding are
>    and process them the same way.  Any new headers should equally
>    be fully cross-implementation.

These are very important points.

In your made-up example you added "bug" (presumably to mean "fixes this bug") and "message-id" ("am-ed from this message"). The latter might make sense, but the former does not belong to the header, as it is not a statement of the fact.

Forcing people to say "this fixes" at the commit time means you do not allow mistakes---it may turn out to be an incorrect or non fix later. When you are amending the commit to say "this does not really fix it", you would want to lose the old "bug" header, but you would want to keep the "message-id" one. There simply is not enough hint as to which ones must be carried across amending in the "we allow people to randomly throw extra headers into the commit object" model. It is not a model--it is chaos.

Also it wouldn't be obvious to other people what got changed while comparing two commits (before and after the amend) if the information is hidden in the header. The right place for that kind of information is in the log message (if the nature of the information is for everybody to see) or in notes.

Another major difference between extra random headers and notes is that the former changes the commit's object name, and if it is due to "random headers", it means you are breaking the object model for no good reason.

Introducing extra headers needs to be done _very_ carefully after thinking things through, judging the pros and cons. Even though we kept the format open to allow us to extend the format to add essential statement of fact that we can make at the commit time (e.g. "encoding"), I do not foresee us adding any official extra headers in near future.