Re: Considering teaching plumbing to users harmful

[Theodore Tso <tytso@mit.edu>]

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