Re: [RFC/PATCHv10 01/11] fast-import: Proper notes tree manipulation

From: Johan Herland <johan@herland.net>
Date: Dec 8, 2009, 02:34 UTC
Message-ID: <200912080334.39337.johan@herland.net>
In-Reply-To: <7vocma1ppc.fsf@alter.siamese.dyndns.org>

On Monday 07 December 2009, Junio C Hamano wrote:

Show 11 quoted lines

> Johan Herland <johan@herland.net> writes:
> > This patch teaches 'git fast-import' to automatically organize note
> > objects in a fast-import stream into an appropriate fanout structure.
> 
> I really hate to sound like a clueless newbie, but that is what I am in
> the area of 'notes', so I have two questions.
> 
>  - What is the semantics of having more than one note to the same commit
>    in the input stream?  Does the 'notes' part also have history and the
>    latest one overwrite the earlier one by creating a new commit that
>    points at the new 'notes' tree?

Yes.

>    I've always thought of 'notes' as an
>    unversioned metainfo, but I realize that versioning them would make
>    sense (you can and obviously would want to inspect the story behind
>    the current note attached to one particular commit).

Correct. Since the notes themselves are organized in a regular ref pointing to a series of commits, the notes for a particular object are indeed versioned. Thus, the first annotation of a commit will happen as part of a commit to the notes ref at some point in time, and a change to that annotation will happen as part of a subsequent commit to the same notes ref at some later point in time. The latter annotation naturally replaces the former, in the same way as a regular file change causes a new blob to replace any blob representing the previous version of the same file.

However, if some object is annotated _twice_ in the _same_ notes commit, then only the last annotation will be reachable. (again, this is the same behaviour as if a regular file is changed twice in the same commit).

Show 6 quoted lines

>  - If however 'notes' want to have a history, how would it interact with
>    this rebalancing of the tree?  Rebalancing makes a lot of sense if the
>    'notes' mechanism deals with the only one latest version because it
>    can keep the optimal look-up performance.  There were some talks about
>    specialized merge strategies that can be made aware of rebalancing, but
>    is there a plan to deal with "git log -p notes" side, and how?

For now (at least), most use cases concern themselves only with the last version of the notes tree, hence no work has been put into prettifying the history of the notes tree.

The notes rebalancing will become part of the same notes commit as the note addition/removal that triggers the rebalancing. This does indeed make the notes commits themselves somewhat uglier, but since the rebalancing only moves notes verbatim from one location to another, it's still fairly simple (with judicious use of e.g. "-M") to find the "actual" changes in a notes commit.

For now, there is no plan to prettify the log of a notes ref, in order to mask away the fanout restructuring. For that matter, there is also no plan to hide the fanout structure itself of the notes tree. It is assumed that if you need to look at a notes tree directly, you can either deal with the implementation details yourself, (or by using future extensions to the notes API; see later patches for the beginnings of those...).

With regards to specialized merge strategies: When merging two notes trees with no specialized strategy, you might end up with two (or more) notes objects annotating the _same_ commit (located at different fanout levels). However, this has already been taken care of by the concatenation code at the tail of the already-merged early part of jh/notes, which automatically concatenates (non-identical) note objects annotating the same commit. Thus, no special merge strategy is needed in order to administer notes trees.

Hope this helps,

...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net