Re: checkout extra files

From: Philip Oakley <philipoakley@iee.org>
Date: Sep 9, 2012, 23:25 UTC
Message-ID: <498B6DF9C7714C278DC3DC9F3EF4A178@PhilipOakley>
In-Reply-To: <7vd31vqcmd.fsf@alter.siamese.dyndns.org>

From: "Junio C Hamano" <gitster@pobox.com>

Show 14 quoted lines

> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
>
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> "Philip Oakley" <philipoakley@iee.org> 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?

Oops I'd forgotten that specific change.

Show 25 quoted lines

>>
>> 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?

a simple link to the gitcli page? or, add the <pathspec> into the checkout options list and a link to a suitable place for that, which can then point to the gitcli.

From my perspective the majority of the top twenty git commands should, within each of their help pages, have an in-text link into one or other of the various 'guide' style articles, which can then be interconnected to each other. This should give the beginner help by directing them away from the details of a man page for the general issues. That is, distinguish which parts are help for those who aren't sure what they need to know, from the those parts that provide the specfic details for those do know.

I hope to have some documentation patches in the next few days on other small misunderstandings I've seen/made. Just battling my windows / msysgit / pu set-up at the moment.