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

From: Kevin Daudt <me@ikke.info>
Date: Sep 30, 2017, 14:32 UTC
Message-ID: <20170930143258.GA20886@alpha.vpn.ikke.info>
In-Reply-To: <alpine.LFD.2.21.1709300523190.27819@localhost.localdomain>

On Sat, Sep 30, 2017 at 05:27:22AM -0400, Robert P. J. Day wrote:

Show 13 quoted lines

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