Theodore Tso wrote:
On Sun, Nov 11, 2007 at 10:50:26PM +0000, Johannes Schindelin wrote:
I beg to differ. The biggest problem with a new user seeing all those
completions is that this user is scared.
Well, if we introduce the new user only to "git subcomand", and the
documentation is relatively gentle, I would suspect would solve most
of the problem. Note BTW, that if your thesis is true, "git help -a"
(which is recommended in the last line of output by "git help") should
cause the typical new user to faint dead away. :-)
Some other areas that would be worth fixing, in terms of user usability.
1) The references to the tutorial, everyday git, etc., don't actually
have working references in the git man page. (i.e., what you see when
you run the command "man git"). It would be nice if that were fixed.
2) The command which are displayed by "git help" should use some
serious rethinking. Ideally, it would be nice if the output fit in a
single 24-line terminal window. Some candidates for removal:
a) prune: "git prune" definitely doesn't deserve to be on the
front and center as displayed by "git help". Maybe replace it
with "gc", but now that we have gc.auto, I'm not sure it's
worth it at all.
prune is definitely scary, and users don't need to know about it until
they've worked with git for quite some time.
b) revert: Is that really that common of a command?
I think I've used it once ;-)
c) show-branch: The output is terrifying without explanation
Indeed. I still don't grok it fully. I tend to use gitk/qgit and some
brainpower to obtain the same result.
There are other commands I'm not so sure about, but it is worth
flagging them. One way that might be helpful is to group the commands
into subcommands, much like gdb does, so you could do something like
"git help other-repos" (where all commands that involve interacting
with other repositories are summarized), and so on.
Ack on that. I suggested it a while back and it appears many liked the
idea. I'm really bad at writing docs though, so it's one of those things
I've been putting off for "some other day".
But yes, I was only proposing to deprecate all usage of git-<bla> in the
documentation.
I agree that de-emphasizing git-<blah> isn't a bad thing. But I think
we need to look at the big picture here, since "git help" is often one
of the first things a new user might try (and obviously very few git
developers look at it, or "prune" probably would have been removed
from git help a long time ago :-), and the last thing that git help
suggests (and so therefore it will very visible to the newbie user),
is "git help -a" --- and that displays every single git command under
creation, porcelain or plumbing, in one gigantic sorted list.
Oops, so much for first impressions. :-)
I agree. Culling the list output by "git help -a" to only show the
porcelain commands would definitely be worthwhile. I'm not sure if it's
worth having a way of showing every installed git command at all (I
know I've never used it anyway).
--
Andreas Ericsson andreas.ericsson@xxxxxx
OP5 AB www.op5.se
Tel: +46 8-230225 Fax: +46 8-230231
-
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
