Re: Deprecate git-fetch-pack?

[Theodore Tso <tytso@mit.edu>]

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.

       b) revert:  Is that really that common of a command?

       c) show-branch: The output is terrifying without explanation

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.

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

	   	    	     	   		 - Ted