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

From: Robert P. J. Day <rpjday@crashcourse.ca>
Date: Sep 30, 2017, 22:04 UTC
Message-ID: <alpine.LFD.2.21.1709301800060.7869@localhost.localdomain>
In-Reply-To: <20170930143258.GA20886@alpha.vpn.ikke.info>

On Sat, 30 Sep 2017, Kevin Daudt wrote:

Show 32 quoted lines

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

  upon re-examination, not so much more clear, as simply not
self-contradictory. just compare the lines in the SYNOPSIS and the
DESCRIPTION sections:

SYNOPSIS
       ...
       git checkout [-p|--patch] [<tree-ish>] [--] [<paths>...]

DESCRIPTION
       ...
       git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...

  those lines clearly represent the same operating mode -- they are
identical in every respect -- but in the first case, paths is
optional, whereas in the second case, it's mandatory.

  it's simply a matter of the forms not matching between the SYNOPSIS
and the DESCRIPTION sections. am i making sense?

rday

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

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