Re: "man git-checkout", man page is inconsistent between SYNOPSIS and details

[Kevin Daudt <me@ikke.info>]

On Sat, Sep 30, 2017 at 05:27:22AM -0400, Robert P. J. Day wrote:
> 
>   just noticed that in "man git-checkout", the SYNOPSIS contains the
> line:
> 
>   git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]
> 
> implying that <paths> is optional, but further down in the
> DESCRIPTION, one reads:
> 
>   git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...
> 
> suggesting that <pathspec> is required.
> 

Hello Robert, thank you for this report.

Git checkout has 2 major modes of operating:

1. Checking out branches (and then update your working tree to match that
  commit.
2. Checking out 1 or more files from a commit.

The first four lines of the synopsis match mode nr. 1. The next two
belong to mode nr. 2.

The pathspec in the synopsis line you are quoting is required, because
that's how you tell git you want mode nr 2. That's why it's not
mentioned between [].  The last section under description explains that
mode. 

Do you feel this distinction needs to be made more clear?

Kevin.