Subject: Re: checkout extra files

From: Junio C Hamano <[email-masked]>
Date: Sun, 09 Sep 2012 11:23:22 -0700

Matthieu Moy <[email-masked]> writes:

> Junio C Hamano <[email-masked]> writes:
>
>> "Philip Oakley" <[email-masked]> writes:
>>
>>> Having said that, it would therefore be better to point folk at gitcli
>>> in a few more places, not just the 'see also' line at the very end of
>>> the general 'git' page, and buried within rev-parse.
>>
>> Didn't we update the very early part of git(1) for exactly for that
>> reason recently?
>
> I don't think many people read git(1) directly, as there are many other
> starting points to learn Git (official tutorial, user-manual, and tens
> of very good tutorial on the web).

Many of which is outside what patches made against to my tree would
be able to fix.  I wonder if we can have some mechanism to easily
notify and help the owners of these material to keep them up to
date.

> On the other hand, reading git-<command> is probably much more
> common, as it is the only place to find exhaustive documentation
> about a particular command.

That "people diving into 'git --help <subcmd>', assuming everything
can be learned there" is a problem within the scope of what we could
control.  For obvious reasons, including "glossary-contents" and
"gitcli" at the beginning of documentation for each and every
subcommand is not a useful solution, and referring the prerequisite
reading for them in git(1) was done as the first step to solve that
issue, and you are essentially saying that it is not enough.

So what is the right second step?