Re: Git in a Nutshell guide

From: Matthieu Moy <matthieu.moy@imag.fr>
Date: Nov 19, 2007, 22:59 UTC
Message-ID: <vpqd4u5zvs3.fsf@bauges.imag.fr>
In-Reply-To: <7v7ikdna24.fsf@gitster.siamese.dyndns.org>

Junio C Hamano <gitster@pobox.com> writes:

Show 5 quoted lines

> I think the ref naming syntax is so commonly used and
> fundamental that we could treat it as prerequiste for individual
> manual pages.  Maybe move the section to git(7)?  That would
> certainly be better than having it in git-rev-parse(1), but does
> not reduce the cross referencing complaints.

Well, obviously, something which isn't addressed by my patch is the fact that some of the documentation an average user needs is in the plumbing man pages.

(Gosh, I was going to cite the manpage for git-log and git-rev-parse as an example, but it has already been fixed :-). Good job !)

git-rev-parse(1) is full of terribly usefull information, and that information is definitely not in the place an average user would look at.

I have no ideal solution for that. git(7) is already really long. Perhaps some "topic man pages" would be good. By "topic man page", I mean "man git-something" where "something" isn't a git command, but a crosscutting concept. For example, here, "man git-refspec" to document reference specifiers like HEAD@{42}, master~55, d71c6c8e24a and friends. "man git-i18n" would be another candidate.

Anyway, my patch is definitely a step forward, even if it's just the first, small one ;-).

-- 
Matthieu