On Thu, Jul 17, 2008 at 09:30:33AM +0200, "Peter Valdemar Mørch (Lists)" wrote: > > As a total git newbie (5 days) coming from svn, I *am* bewildered. Even > sticking to porcelain, it is a feature-rich new tool I have in my hands! > > I'm missing clarity about what is porcelain and what is plumbing. `git > help` shows The top-level man page has a listing of what is porcelain and what is plumbing --- although there is some disagreement. Johannes was complaining about people using git rev-parse in tutorials and saying that there was no way that was porcelain, but in fact it is *not* listed as plumbing in the git man page. So I don't think there is really a strong black-and-white category, but rather a certain set of shades of gray, as it were. > Is this list exactly the list of porcelain commands? Then say so there. > Neither `git help diff` nor `git help ls-tree` say whether they are > porcelain or plumbing commands. `git help diff` mentions git-diff-index, > which i suspect is plumbing. When I read a man page, it would be nice to > know whether a command (either the topic of the page or another > mentioned command) is intended as porcelain or not. My personal long-standing complaint is that there are certain man pages like "git log" where in order to see all of the options which it can take, the man page for git-log redirects you to a man page for plumbing. Great way to scare the users. :-) Have you taken a look at the intro-level materials such as "Everyday Git in 20 commands or so"[1], the git tutorial[2], the official "Git's User Manual"[3], or the "Git-SVN crash course"[4]? Those are probably the best place to begin --- and to basically treat the git man pages as reference materials with a huge number of controls that you won't use or need to use for a long time --- if ever. It's like the 10,000 features hidden inside Microsoft Office. The features are all indispensable to *someone*, but everyone has a different set of the 100 features which they all *have* to have. (And of course, the 20 or so features that everyone really uses. :-) > All of this of course assumes that there is consensus and a clear > distinction between what is porcelain and what is plumbing which I'm > don't even know if there is. I don't think so. It's like what the judge said about pornography --- I know it when I see it. :-) And note that there's nothing *wrong* with using plumbing commands. It's just that from a pedagogical point of view, they might not necessarily be the best place to start. - Ted [1] http://www.kernel.org/pub/software/scm/git/docs/everyday.html [2] http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html [3] http://www.kernel.org/pub/software/scm/git/docs/user-manual.html [4] http://git.or.cz/course/svn.html -- 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
