On Fri, Apr 24, 2009 at 10:18:47AM -0400, Jeff King wrote: > 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). I'd be in favor of that. --b. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html