Re: Git Community Book

["Scott Chacon" <schacon@gmail.com>]

On Fri, Sep 5, 2008 at 12:41 PM, Junio C Hamano <gitster@pobox.com> wrote:
> "Scott Chacon" <schacon@gmail.com> writes:
>
>> Also, the last section of the book is on some of the plumbing - mostly
>> stuff I've found difficult to pick up with the existing documentation
>> while re-implementing stuff in Ruby.  I would really appreciate it if
>> someone could proofread some of these chapters for errors:
>>
>> http://book.git-scm.com/7_the_packfile.html
>
> Nice pictures.  You might also want to know that code for reading pack idx
> version 2 was backported to 1.4.4.5 for people who are stuck on 1.4.4
> series for whatever reason.
>
> What is the target audience of this section?  If it is written for a mere
> curious type, or if it is written to give "here is the general idea, for
> more details read the source", the level of detail here would be Ok.
>
> If you are writing for people who want to (re)implement something that
> produces these files, you might want to at least say that offset/sha1[]
> table is sorted by sha1[] values (this is to allow binary search of this
> table), and fanout[] table points at the offset/sha1[] table in a specific
> way (so that part of the latter table that covers all hashes that start
> with a given byte can be found to avoid 8 iterations of the binary
> search).
>
> <data> part is just zlib stream for non-delta object types; for the two
> delta object representations, the <data> portion contains something that
> identifies which base object this delta representation depends on, and the
> delta to apply on the base object to resurrect this object.  ref-delta
> uses 20-byte hash of the base object at the beginning of <data>, while
> ofs-delta stores an offset within the same packfile to identify the base
> object.  In either case, two important constraints a reimplementor must
> adhere to are:
>
>  * delta representation must be based on some other object within the same
>   packfile;
>
>  * the base object must be of the same underlying type (blob, tree, commit
>   or tag);
>
>> http://book.git-scm.com/7_raw_git.html
>
> I am guessing this is for Porcelain writers who use plumbing.  Please
> don't teach echoing into .git/refs/...  but DO teach using update-ref with
> the -m option.  We do not want people's random Porcelains flipping the tip
> of branches without leaving trail in reflog for users to use to recover
> from mistakes.
>

I've implemented all of these and Linus's fixes and suggestions.
Thanks for the feedback.

To answer your earlier question, these docs are basically for people
working on bindings/re-implementations in other languages, since there
is no real linked library available yet, as a primer before they dig
into the source, or possibly so they don't have to.

I'm not fantastic at C, so it took me a while in some cases - figuring
out that the size listed in the object header was not the actual size
of the data, but the size of it when expanded, for example, was not
very easy to do.  I've been doing a lot of work on re-implementations
in Ruby and ObjC because I can't easily make real bindings, so I
thought I would add things that I could not easily find in the docs
for others that are trying in other languages.

If you want, I could create a patch for any of this stuff to
Documentation/ (that goes for the whole book), but someone will have
to tell me which parts might be useful to add.

Thanks again for taking the time!
Scott