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

["Robert P. J. Day" <rpjday@crashcourse.ca>]

On Sat, 30 Sep 2017, Kevin Daudt wrote:

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

  hmmmmm ... let me read it again before i answer that.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================