Re: extra headers in commit objects

From: Shawn O. Pearce <spearce@spearce.org>
Date: Feb 3, 2010, 21:04 UTC
Message-ID: <20100203210407.GG14799@spearce.org>
In-Reply-To: <7vwryugifz.fsf@alter.siamese.dyndns.org>

Junio C Hamano <gitster@pobox.com> wrote:

Show 12 quoted lines

> "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.

Yes, sorry, of course that is what I meant. Thanks for the clarification.

To add to that, "after encoding, if encoding is present".

Show 15 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.

This all came out of what appears to be a tool to bridge another VCS system data into Git. Ala git-svn.

We all know that some other systems, e.g. SVN, permit adding additional properties to commits, and that often these are used to make statements like "Fixed bug NNNN", and bug tracking systems integrate into SVN by reading or updating those properties.

So you, Nico, myself, might all agree that "bug" does not belong in the header, but many others see it like SVN sees additional properties on a revision, and thus it goes there.

Hence the artifical example.  It seems that it is not that artifical
outside of our mailing list.

> 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.

Yup, happens often.

Show 5 quoted lines

> 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.

Exactly. That's what I had thought our position was, for exactly this reason, it very quickly devolves into a chaos we can't reason about, let alone write code to support for end-users.

Show 5 quoted lines

> 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.

I'm afraid users might insert their own headers, then come report the bug that `git log` and `git show` don't make those headers visible when formatting the commit. After all, they show the author committer, and parent information when you use the right flags.

We'll of course say, its not in the message, and suggest using the footer style like our Signed-off-by lines, or notes, which appear below the message if requested.

Show 5 quoted lines

> 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.

Right, me neither, because everything that has been proposed for an extra header (e.g. bug id, Message-Id from the email it as git-amed from, rename tracking, ...) has all been suggested to be better positioned in the message itself, or in a note, or not at all...

-- 
Shawn.