From: Andreas Ericsson <ae@op5.se>
Date: Mon, 12 Nov 2007 10:15:49 GMT
Subject: Re: Deprecate git-fetch-pack?
Message-ID: <473827D5.2070908@op5.se>
In-Reply-To: <20071111235819.GB7392@thunk.org>

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@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231