Re: [PATCH] Add a birdview-on-the-source-code section to the user manual

From: J. Bruce Fields <bfields@fieldses.org>
Date: May 9, 2007, 03:18 UTC
Message-ID: <20070509031803.GA27980@fieldses.org>
In-Reply-To: <Pine.LNX.4.64.0705081709230.4167@racer.site>

On Tue, May 08, 2007 at 05:10:47PM +0200, Johannes Schindelin wrote:

Show 7 quoted lines

> 
> In http://thread.gmane.org/gmane.comp.version-control.git/42479,
> a birdview on the source code was requested.
> 
> J. Bruce Fields suggested that my reply should be included in the
> user manual, and there was nothing of an outcry, so here it is,
> not even 2 months later.

Looks helpful, concise, and to the point.  Neat-o.

Acked-by: J. Bruce Fields <bfields@citi.umich.edu>

Comments, nothing major:

> +If you grasp the ideas in that initial commit (it is really small and you 
> +can get into it really fast, and it will help you recognize things in the 
> +much larger code base we have now), you should go on skimming `cache.h`, 
> +`object.h` and `commit.h`.

Might want to add "in a recent commit"?--it's not clear that you've transitioned away from talking about the initial commit.

> +This is just to get you into the groove for the most libified part of Git: 
> +the revision walker.

Unless the reader has already been hanging out on the mailing list a while, "most libified" may not mean much to them yet at this point.

The organization of the next bit is slightly confusing: we're set up to expect a longer lecture on the revision walker, but instead there's just the historical note on git-rev-list, a mention of 'revision.c', 'revision.h', and 'struct rev_info', and then it rapidly digresses into discussing builtins.

Which actually is fine, but just a few small markers of where we are in the discussion might be reassuring--a section header or two, maybe a little more emphasis on the pointers you're giving, like: "take a moment to go read revision.h and revision.c now, paying special attention to struct rev_info, which ....".

--b.