Hi, On Wed, Dec 09, 2009 at 05:27:37PM +0900, Nanako Shiraishi wrote: > Quoting SZEDER Gábor <szeder@xxxxxxxxxx> > > > [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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html