Re: Git Community Book

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 5, 2008, 19:41 UTC
Message-ID: <7vmyimv0qr.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <d411cc4a0809051208k2a15c4a7te09a6979929e52f7@mail.gmail.com>

"Scott Chacon" <schacon@gmail.com> writes:

Show 6 quoted lines

> 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.