Re: [doc] User Manual Suggestion

From: David Abrahams <dave@boostpro.com>
Date: Apr 24, 2009, 17:28 UTC
Message-ID: <91225E09-505A-4CD6-AC8E-FBB500A95984@boostpro.com>
In-Reply-To: <20090424141847.GD10761@coredump.intra.peff.net>

On Apr 24, 2009, at 10:18 AM, Jeff King wrote:

Show 15 quoted lines

> On Thu, Apr 23, 2009 at 05:31:13PM -0400, David Abrahams wrote:
>
>>> I think the main problem, then, is that the tools have a UI that is
>>> somewhere in the middle.
>>
>> Well, "the UI" (how many do we really have for Git?) is spread  
>> across the
>> spectrum.  The git command-line alone lets you do incredibly low- 
>> level
>> things that "nobody should ever do" and some really high-level  
>> things that
>> are everyone's bread-and-butter.  There's no obvious distinction.
>
> I think this is a bit better than it used to be. Plumbing commands are
> mostly hidden outside of the user's PATH.

Huh?

git hash-object git cat-file -t ... git ls-tree git rev-parse git write-tree git commit-tree

...

These are just some of the ones I learned about by reading John Wiegley's "Git From the Bottom Up."

Maybe I'm wrong about rev-parse, but for the most part, having all these low-level commands available through the same executable that's used for "git add," "git merge," "git commit," et. al. makes the whole shebang hard to approach. It would be better for users if the low- level stuff was accessed some other way.

Show 7 quoted lines

> A lot of that is historical baggage. The original git was not a VCS  
> but
> rather a _toolkit_ for building a VCS. So the natural place for  
> talking
> about parsing revisions was rev-parse, because that was the only way  
> to
> access the revision parsing code. :)

I understand that, but it doesn't change the present reality.

> I think a lot of documentation like the "specifying revisions" section
> of rev-parse might benefit from being split into its own "concept"
> section, like gitrevisions(7).

Yes, please.

[excuse me, but what the #@&*! is "porcelainish" supposed to mean? (http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html )]

Show 8 quoted lines

> And commands which allow specifying
> revisions (at least the major ones, like log, diff, etc) should
> reference it (but not include it directly, as we do with some
> documentation snippets -- the point is to make the user aware that  
> they
> are learning a separate concept that can be applied in multiple  
> places,
> and to give that concept a name).

Very nice.

-- David Abrahams BoostPro Computing http://boostpro.com