Re: [doc] User Manual Suggestion

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

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.

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

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.

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

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.

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.

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.

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