On Fri, Apr 24, 2009 at 10:18:47AM -0400, Jeff King wrote:
Show 30 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. 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).