Re: [PATCH] doc: technical details about the index file format
- From
Nguyen Thai Ngoc Duy <pclouds@gmail.com>
- Date
- Mar 2, 2011, 11:43 UTC
- Message-ID
- <AANLkTimKT2dgPu_0L=K-14e6bBCgPhiQ59AmPWp7y6vg@mail.gmail.com>
- In-Reply-To
- <7voc5ucb6b.fsf@alter.siamese.dyndns.org>
On Wed, Mar 2, 2011 at 1:02 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 5 quoted lines
>> I wonder if we should also point to relevant source files, so if this >> document becomes out of date, the readers can jump in the source and >> verify themselves (perhaps coming up with patches to this doc)? > > I suspect that is a sure way to guarantee the document to go stale.
No it does not. The point is to make it easier for readers to help themselves when they suspect the document is not entirely correct.
> I didn't like the way I explained the cache-tree entry order. Was it > understandable?
It is, although I'm wondering if it's just like memcmp() order with parent component cut out.
Show 6 quoted lines
> I am wondering if an illustration with an example might be in order. I > think anybody halfway intelligent may be able to get a fuzzy idea of what > is going on by looking at the output from test-dump-cache-tree after > "reset --hard && write-tree" and then by comparing it with the output from > test-dump-cache-tree after running ">t/something && git add t/something" > (which invalidates the top-level tree and t/ subtree).
A short example would be great. test-dump-cache-tree might not be. Last time I read its output, I wasn't sure I understood. Maybe because I ran it on git.git and did not compare two outputs.
Show 6 quoted lines
> But a well written > documentation should be able to help clarifying the idea obtainable that > way. I don't think what I wrote in the previous message is sufficient > even for that (i.e. comparing the two output would give you better > explanation of what is going on than what I wrote--iow, what I wrote may > not be very useful for people who are motivated to learn).
-- Duy