From: SZEDER Gábor <szeder@ira.uka.de>
Date: Wed, 09 Dec 2009 09:45:32 GMT
Subject: Re: help: bisect single file from repos
Message-ID: <20091209094532.GS18686@neumann>
In-Reply-To: <20091209172737.6117@nanako3.lavabit.com>

Hi,


On Wed, Dec 09, 2009 at 05:27:37PM +0900, Nanako Shiraishi wrote:
> Quoting SZEDER Gábor <szeder@ira.uka.de>
> 
> > [1] - 'git cherry-pick' doc says the following:
> >
> >   <commit>
> >     Commit to cherry-pick. For a more complete list of ways to spell
> >     commits, see the "SPECIFYING REVISIONS" section in git-rev-parse(1).
> >
> > What?  "A _more_ complete list"!?  Well, it's not very hard to be more
> > complete than this, there is not a single way described here (;
> 

> I agree that "more" shouldn't be in that sentence, and I understand
> your hesitation to read plumbing manual pages, but I don't think it
> is a sane solution to the issue to repeat how to name a commit in
> manual pages for every single command to bloat the two line
> description you quoted into a half-page paragraph.  Even within that
> two lines, the real information that should be in the manual for
> cherry-pick is only three words "Commit to cherry-pick" and the rest
> is to help people who don't know.

I agree, that's why I proposed "a _section_ about specifying these
commits" in the more relevant part of my previous email you did not
quote.

The description of the "<commit>" option would remain almost the same,
but it will now refer to a dedicated section about specifying commits
below, but still in the same manpage.  This new dedicated section
would contain the list of three, five, N most common ways to specify a
commit, avoiding the bloatage in the options section.  And for those
who really want to dig deep, this dedicated section will refer to 'git
rev-parse' for the complete list.

And this would not be the first time we document something in many
places, think of '--pretty' and diff options, for example.


Best,
Gábor