Re: help: bisect single file from repos

[walter harms <wharms@bfs.de>]

SZEDER Gábor schrieb:
> 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.
> 
> 

It would be no problem when you have the description multiple times.
Important is that they use the same words for the same things
and add examples. Most people that use git have a fair idea what they
want but not how to do it. git is new an you can not assume that
even basic principles are known to the general (programmer) community.
So you need to make extra effort to explain it all over again.

re,
 wh