Re: [PATCH] doc: technical details about the index file format

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 2, 2011, 06:02 UTC
Message-ID: <7voc5ucb6b.fsf@alter.siamese.dyndns.org>
In-Reply-To: <AANLkTi=GhdfWCyx7MN3w0ZPhqKHcC1e6RmPeZt67OeqG@mail.gmail.com>

Nguyen Thai Ngoc Duy <pclouds@gmail.com> writes:

> Looks good. I don't really like ending a sentence with semicolon, but
> that's just my taste.

I tend to do enumerated list like "A; B; and C." Perhaps just a personal taste.

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

I didn't like the way I explained the cache-tree entry order. Was it understandable?

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