Re: Git Community Book

["Felipe Contreras" <felipe.contreras@gmail.com>]

On Sat, Sep 6, 2008 at 12:34 AM, Scott Chacon <schacon@gmail.com> wrote:
> 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.

I have experience mixing C and Ruby code if you are interested, it's
actually quite easy.

I also think a shared library would make sense.

Keep up the good work ;)

-- 
Felipe Contreras