Re: help: bisect single file from repos

From: Nanako Shiraishi <nanako3@lavabit.com>
Date: Dec 9, 2009, 08:27 UTC
Message-ID: <20091209172737.6117@nanako3.lavabit.com>
In-Reply-To: <20091209012855.GA3208@neumann>

Quoting SZEDER Gábor <szeder@ira.uka.de>

Show 8 quoted lines

> [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.

Maybe it is a better idea to rewrite this to "See 'basic concepts' manual for how to specify a commit", and create a new 'basic concepts' manual that describes these things the readers must know to effectively use the main part of the manual.  And make sure that we try very hard to keep the 'basic concepts' manual short, by eg. making a goal to keep it less than N printed pages.

To decide the value of 'N', somebody needs to first think and list the topics that need to be covered by 'basic concepts'. Something like this?

 * What are committed states, the state in the index and the state in the working tree.
 * How to name a commit.
 * How to name a range of commit (move part from the rev-parse manual).
 * How to specify options, revisions and files on command line (move part from the gitcli manual).

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/