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

[Johan Herland <johan@herland.net>]

On Monday 07 December 2009, Junio C Hamano wrote:
> 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).

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