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

On Sat, 30 Sep 2017, Kevin Daudt wrote:

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

quoted

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