Re: [PATCH] rev-list: add "--full-objects" flag.

From: Linus Torvalds <torvalds@osdl.org>
Date: Jul 11, 2005, 17:53 UTC
Message-ID: <Pine.LNX.4.58.0507111045380.17536@g5.osdl.org>
In-Reply-To: <m1irzh74m0.fsf@ebiederm.dsl.xmission.com>

On Mon, 11 Jul 2005, Eric W. Biederman wrote:

Show 5 quoted lines

> 
> I'm having the worst time putting together a mental model of how git
> works, and the documentation is spotty enough that it hasn't been
> helpful.  So I am wading through the code.  It seems every time I turn
> a corner there is another rough spot.

Btw, I know I'm bad at writing docs, but what I _do_ enjoy doing is answering reasonably specific technical questions, and maybe somebody else can write docs by taking advantage of me that way.

I tried to write the tutorial in a way that it also tries to explain how git works (not just a "do this", but a "you update the index file and then write the result out as a tree object"), but it obviously covers a fairly limited part of what git actually can do, and at the same time it doesn't go into a lot of detail.

And part of that is not just my inability to write documentation, it's also that I just have the wrong "view" of the project, ie I probably just take a lot of things for granted and consider them obvious, even though they aren't, and then I probably occasionally explain things that aren't worth explaining, because either they _are_ obvious, or people just don't care and they are irrelevant.

I'd love to see somebody write up more of a "this is how you use git" kind of tutorial, _and_ on the other hand more of a low-level explanation of the notion of an object store where objects refer to each other by their SHA1 names, and how that is represented in the filesystem and/or in packs.

Something with a few pictures would be great (ie screenshots of gitk, but also something that tries to just visually show hot tags point to commits that point to parents and trees, and trees pointing to other trees and then blobs).

All things that I'm a complete idiot at, but that would help users visualize what the heck git is actually _doing_, so that they don't just parrot some magic command line that they don't understand, but can actually reason about what they are doing.

I think a lot of people do understand this, but yes, the docs are kind of lacking.

			Linus