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

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