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