git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: Kevin Daudt <me@ikke.info>
To: "Robert P. J. Day" <rpjday@crashcourse.ca>
Cc: Git Mailing list <git@vger.kernel.org>
Subject: Re: "man git-checkout", man page is inconsistent between SYNOPSIS and details
Date: Sat, 30 Sep 2017 16:32:58 +0200
Message-ID: <20170930143258.GA20886@alpha.vpn.ikke.info> (raw)
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:
> 
>   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.

  reply index

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-09-30  9:27 Robert P. J. Day
2017-09-30 14:32 ` Kevin Daudt [this message]
2017-09-30 15:01   ` Robert P. J. Day
2017-09-30 22:04   ` Robert P. J. Day
2017-10-01  3:49     ` Junio C Hamano
2017-10-01 10:05       ` Robert P. J. Day
2017-10-02  0:29         ` Junio C Hamano
2017-10-11  2:39           ` [PATCH] checkout doc: clarify command line args for "checkout paths" mode Junio C Hamano
2017-10-11  3:22             ` Jonathan Nieder
2017-10-11  5:02               ` Junio C Hamano
2017-10-11  5:16                 ` Jonathan Nieder

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170930143258.GA20886@alpha.vpn.ikke.info \
    --to=me@ikke.info \
    --cc=git@vger.kernel.org \
    --cc=rpjday@crashcourse.ca \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

git@vger.kernel.org mailing list mirror (one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/
       or Tor2web: https://www.tor2web.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox