Re: [PATCH v2] Group the default git help message by topic

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 14, 2010, 17:24 UTC
Message-ID: <7vvd9la5nq.fsf@alter.siamese.dyndns.org>
In-Reply-To: <AANLkTimFUGkYeZaXA7BqX8ghsHX_gGYRK69ScHMXbw2l@mail.gmail.com>

Scott Chacon <schacon@gmail.com> writes:

Show 21 quoted lines

> Though the implementation of the solution is undeniably more elegant,
> I have some serious issues with the output.  As you mention next,
> 'show-branches' is second in the list, which is an issue, but there
> are several more.  'am', 'revert', 'daemon', 'shell', 'rebase' - none
> of these are appropriate for someone running 'git' and trying to see
> where to start.  If we put those aside, all we have is a big list of
> commands again which adds almost no value to what we had before.
> ...
>> If readers notice that there are some commands that are out of fashion
>> (e.g. I don't think many people use show-branch anymore in the presence of
>> "log --oneline --graph" and friends) listed in the "git help" output, that
>> is a _good thing_.  It will give us an incentive to keep the Everyday
>> document up to date, and with the effort spent for that, "git help" will
>> automatically be kept up to date as well for free ;-)
>
> That's a fine goal, but I feel like it shouldn't be an "everyday"
> document that generates that output, it should be a "beginner"
> document or a "how to start using Git" document that isn't really in
> the Git source.
>
> Thoughts?

Three points.

 - The fact that you noticed "show-branches" is _a good thing_.  If it
   doesn't deserve to be "this is the list of often used commands" given
   by "git help", it shouldn't be in (an early part of) Everyday either.

 - I think the "git help" list and "Everyday" document should serve the
   same purpose for two classes of audiences, ones that prefer online vs
   ones that prefer offline.  "Repository Maintenance" are pushed down in
   the Everyday document as they are sometimes needed but should not be
   necessary in "Everyday" operation.  I think it may be a good idea to
   stop generate-cmdlist.sh early before reading Everyday to the end,
   which would cut the cruft from "git help" output.

 - I do not necessarily agree with your notion that "git help" output is
   for "someone trying to see where to start".  To me, it is primarily to
   serve as a reminder for people who have been casually using git for
   some time (i.e. "I know what I do but I don't offhand recall how it is
   spelled").  Not everybody will stay as a newbie.

I think the last point is the crux of disagreement between us. You have been in the "git teaching" business for a long time, and I am very much willing to be pursuaded, together with other participants on the list.