Re: help: bisect single file from repos

From: SZEDER Gábor <szeder@ira.uka.de>
Date: Dec 9, 2009, 09:45 UTC
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:

Show 11 quoted lines

> 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 (;
>

Show 8 quoted lines

> 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