Re: [PATCH] Documentation/checkout: clarify description
- From
Jeff King <peff@peff.net>
- Date
- Jun 1, 2010, 06:10 UTC
- Message-ID
- <20100601061046.GA7360@sigill.intra.peff.net>
- In-Reply-To
- <20100530084153.GA5447@progeny.tock>
On Sun, May 30, 2010 at 03:41:53AM -0500, Jonathan Nieder wrote:
> To the first-time reader, it may not be obvious that ‘git checkout’ > has two modes, nor that if no branch is specified it will read > from the index.
OK, I can see how we might not explain the modes well, but...
Show 14 quoted lines
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt > index 4505eb6..99bd7f2 100644 > --- a/Documentation/git-checkout.txt > +++ b/Documentation/git-checkout.txt > @@ -15,26 +15,32 @@ SYNOPSIS > > DESCRIPTION > ----------- > +Retrieves files from the index or specified tree and writes them > +to the working tree. > > -When <paths> are not given, this command switches branches by > -updating the index, working tree, and HEAD to reflect the specified > -branch.
How is this first paragraph helping? It seems to be describing just one mode. You then go on to describe each mode in turn, which makes sense, but this first paragraph just seems out of place. If you're going to say anything, you should say "there are two different modes, one for X and one for Y. The first mode is...".
Show 5 quoted lines
> +'git checkout' [-b <new branch>] [<branch>]:: > > + When <paths> are not given, this command switches branches by > + updating the index, working tree, and HEAD to reflect the > + specified branch.
In 76cfadf, I split this into
git checkout [<branch>] git checkout -b <new branch> [<start_point>]
I wonder if we should do the same here (the distinction is that <start_point> is treated differently from <branch>, especially with respect to creating a detached HEAD).
Also, does it make sense to say "When <paths> are not given"? The "this command" presumably refers to the one directly above, which has no <paths>. Might it be easier to understand if we say "in this form of the command" or something like that? Since we are now listing each form in turn, the user can presumably figure out which form they are trying to use.
-Peff