On Sat, Sep 6, 2008 at 12:34 AM, Scott Chacon <schacon@xxxxxxxxx> wrote: > On Fri, Sep 5, 2008 at 12:41 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote: >> "Scott Chacon" <schacon@xxxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
