Re: [doc] User Manual Suggestion

[Jeff King <peff@peff.net>]

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. Unfortunately there are still
some warts, like the fact that users may be referred to "git help
rev-parse" to learn about how revisions are specified. But they have to
wade through the information on the "rev-parse" command, which is
something that most users will never need to know or care about.

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

-Peff