From: Junio C Hamano Date: Wed, 02 Mar 2011 06:02:20 GMT Subject: Re: [PATCH] doc: technical details about the index file format Message-ID: <7voc5ucb6b.fsf@alter.siamese.dyndns.org> In-Reply-To: Nguyen Thai Ngoc Duy 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).