On Fri, Apr 24, 2009 at 03:00:19PM -0400, David Abrahams wrote:

quoted text
>> How did you find out about them?
>
> The first time?
>
>  $ man git
>
> [...]
>
> which makes no distinction [between porcelain and plumbing].

Really? The command list in my version is divided into "HIGH-LEVEL
COMMANDS (PORCELAIN)" and "LOW-LEVEL COMMANDS (PLUMBING)", with the
commands you mentioned falling into the latter. And skimming "git log
Documentation/git.txt", it looks like it has been that way for some
time.

There is a little discussion under the plumbing section of what plumbing
is. It could perhaps be more emphatic in warning regular users away.

quoted text
>> They are not in your PATH, so shell
>> completion doesn't find them.
>
> Huh?  `which git` works.  ls-tree is an argument to git as far as I know.

Yes, but shell completion will never present you with the text
"ls-tree". You have to have found out about it somewhere else (and
completion used to show, because git-ls-tree was in the PATH).

quoted text
>   $ xxx [--]help
>
> is usually OK if I already know xxx pretty well and just want a  
> refresher.  If know I'll need a little more than that, I use man straight 
> away.

git --help shows a list of common commands, but otherwise "git help
foo" and "git foo --help" _do_ show the manpage. It may be that "man
git" could use some cleanup; specific suggestions are welcome.

quoted text
> What is "porcelain," please?  This is one among many examples of jargon 
> used only (or encountered by me for the first time) in the Git community.

I think I ended up explaining it later in my email, but let me know if
you are still confused.

quoted text
>> The idea was to give a uniform calling convention without
>> unnecessarily confusing users by presenting a large number of
>> infrequently-used commands.
>
> It's not working, I'm sorry to say.

Right, that's why I'm trying to figure out why you are hung up on the
low-level commands. The idea was that you wouldn't need to be exposed to
them at all, but obviously you were (or if you were exposed, it would be
in a list that was clearly marked as "this is low-level stuff that you
don't really need to worry about". So I'm trying to figure out where it
went wrong.

quoted text
>> At any rate, it is too late to change the calling convention for
>> plumbing.
>
> I disagree.  You can leave the old functionality there in a "deprecated" 
> state and change the way you advertise it.

But does that really help? It means that "git hash-object" is still
there, which I thought was the problem you had. You can argue that it
wouldn't be advertised to users, and so wouldn't be a problem, but that
is _already_ the strategy we are using. So either that strategy is fine,
in which case we are on the right track but may still have some work to
do in properly implementing it. Or it's not, in which case your proposal
is no better.

quoted text
> It would even help a lot if the plumbing were all spelled "git-xxx"
> and the high level stuff were "git xxx."

Differentating calling conventions like that was proposed when dashed
forms were deprecated and removed from the PATH. But if we had dashed
forms for plumbing (i.e., not forwarding them via the "git" wrapper),
then you have to do one of:

  - put them in the user's PATH. Now tab completion or looking in your
    PATH means you see _just_ the plumbing commands, and none of the
    high level ones. Which is one of the reasons they were removed from
    the PATH in the first place (due to numerous user complaints).

  - put them elsewhere, and force plumbing users to add $GIT_EXEC_PATH
    to their PATH. That becomes very annoying for casual plumbing users.
    If you come to the mailing list with a problem, I would have to jump
    through extra hoops to ask you to show me the output of "git
    ls-files".

Not to mention that the git wrapper does other useful things besides
simply exec'ing. For example, it supports --git-dir, --bare, etc.
So the problem is that the low-level commands _are_ still useful, and
many people still want to call them, just like regular git commands.
It's just that they are numerous and low-level, which makes them
daunting for new users.

And it has become obvious over several years of the git mailing list
that users, once they see mention of a command, must start investigating 
it to find out if and how it is useful. And I am not saying that is a
failing of users; on the contrary, I think it is quite a healthy
behavior on a unix-ish system. But it means that if we want not to
advertise low-level commands, we have to be very careful about the ways
in which we mention them.

Perhaps it would make sense for each plumbing command's man page to
start with something like "this is a low-level command used for
scripting git or investigating its internals. For high-level use, you
may be more interested in $X", where $X may be "git commit" for
write-tree, commit-tree, etc. And that would at least help intercept
users before they get too confused.

quoted text
>>> [excuse me, but what the #@&*! is "porcelainish" supposed to mean?
>>> (http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html)]
>>
>> Heh. That one is particularly egregious, because it rests on several
>> layers of git jargon. The low-level tools are plumbing, like pipes and
>> valves.
>
> ? I use the valves on my kitchen sink all the time.

Sorry, I meant the ones under the sink, that you would use if you were
replacing the faucet. I would call the ones above "taps". But hopefully
you get a sense of the distinction between plumbing and porcelain.

-Peff
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html