On Apr 24, 2009, at 4:24 PM, Jeff King wrote:
On Fri, Apr 24, 2009 at 03:00:19PM -0400, David Abrahams wrote:
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.
Sorry, you are totally right.
The list is just so crazy-long; I may have skimmed it.
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).
$ 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.
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.
Nope; I'm fine now. It's not a great analogy, because everyone who
uses a sink ends up dealing with spigots and valves, but I get it.
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.
I'm sorry that I can't be much help in that department. If I really
knew how I ended up with that wrong impression, I probably would have
corrected it already. It's weird; git is composed of ideas that are
all very familiar to me (reference-counted management of immutable
data, hashing, etc.) yet for me, getting to know it has been really
tough. By contrast, for example, subversion was instantly
understandable when I pawed through the SVN book.
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.
You've got me stumped there, I have to admit.
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".
I see your point.
llgit xxx
?
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.
Sounds like a great idea to me.
[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.
I know, but the point is, they're not porcelain. They're "plumbing
fixtures."
I think UI/API works way better than porcelain/plumbing. We are,
after all, programmers. It would also be good to link to a definition
any time you use a term of art in the docs. I would even do that in
the case of UI/API since the distinction could appear to be subtle.
I should also say, most of the docs and interfaces I see in Git (and
its wrappers, web interfaces, etc.) give the SHA1 hashes way too much
exposure. The times when it's actually more convenient to use a hash
instead of one of the other notations are rare, and if hashes weren't
so exposed I bet most interfaces would make those other names more
available. One reason I think hashes retain their prominent exposure
is that you have no other reasonably stable way of referring to
commits, since branch~NN counts backward from HEAD. Adding such a
thing would help.
Oh, one other specific issue: the rev-parse manpage uses $GIT_DIR
without saying what it is. I *think* that means the root of the
working copy and has nothing to do with environment variables, but
it's hard to be sure, and if I'm right about that, it's misleading
notation.
Someone needs to get gitiseasy.org/gitiseasy.net and then provide
content that lives up to the name :^)
--
David Abrahams
BoostPro Computing
http://boostpro.com
--
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