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