Re: [PATCH] Documentation/checkout: clarify description

[Jeff King <peff@peff.net>]

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

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

> +'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