Re: GTP/0.1 terminology 101: commit reels and references

[Sam Vilain <sam@vilain.net>]

Josh, I'm cc:'ing the main list with this one as well, as I think it
falls into the scope of discussions of wider interest than the rfc- and
implementation-specific discussions that (I envisaged would) happen on
the gittorrent list.

On Sun, 2008-07-27 at 23:53 -0400, Joshua Roys wrote:
> Here's some terms, as best as I understand them.
> 
> The *Commit Reel* is a sequence of objects between two reference points, 
> sorted in a deterministic fashion.  The two reference points are 
> *Reference* objects, or a signed tag containing a collection of git refs 
> (similar to the output from `git show-ref`).

Yes, that's right.  We have the two slightly ambiguous terms, "refs",
which mean the same thing as the rest of git, and "References", which
are more like .git/packed-refs.  Perhaps this is a good time to pick a
better name.  "Slice" would be an accurate term, though it's certainly
tempting to pick another term from the tape taxonomy, such as "Splice"¹
or "Mark"².

>   Commit reels can also, and generally do, include the objects required
>  for a specific commit.

Yes.  The only times where they wouldn't contain all the objects
required for the commits within the reel, is when those objects happened
to be contained by a previous reel.

This is one of the design decisions which I think may be a mistake; a
less expensive to calculate definition of a reel would be *all* objects
between the starting and ending Reference objects.  The current
definition requires a hash index of objects in each reel, which must be
consulted once for all objects when creating the reel index.

> As an example, a commit reel could be the set of objects between the 
> v2.6.25 and v2.6.26 tags of the Linux kernel.  The only thing we would 
> need added to those tags is the list of heads (and tags) at the time of 
> the tagging.

Correct.  It represents all of the changes in a given repository over a
period of time.

> Those two structures form the basis for two *Peer Wire Protocol* (PWP) 
> messages, Reels and References.
> 
> Any questions, corrections, or rotten vegetables?

No, I think that's all good so far...

Cheers,
Sam.

¹ - see
http://en.wikipedia.org/wiki/Reel-to-reel_audio_tape_recording#Description
² - as used by the old unix "mt", see eg
http://docs.sun.com/app/docs/doc/816-0210/6m6nb7mf3?a=view