Subject: Re: Considering teaching plumbing to users harmful

From: "Peter Valdemar Mørch (Lists)" <[email-masked]>
Date: Thu, 17 Jul 2008 09:30:33 +0200

Johannes Schindelin Johannes.Schindelin-at-gmx.de |Lists| wrote:
> there have been a number of occasions where I came across people trying to 
> be helpful and teaching Git newbies a few tricks.
> 
> However, in quite a number of cases, which seem to surge over the last 
> weeks, I see people suggesting the use of rev-parse, ls-tree, rev-list 
> etc.

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 most commonly used git commands are:"  add .. tag.

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.

Also, I'm guessing that some switches for some porcelain commands have 
plumbing purposes and vice versa. I hope not, but if so that would be 
nice to have documented in 'git help *'

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.

Peter
-- 
Peter Valdemar Mørch
http://www.morch.com