From: Junio C Hamano <gitster@pobox.com>
To: "Robert P. J. Day" <rpjday@crashcourse.ca>
Cc: Git Mailing list <git@vger.kernel.org>
Subject: Re: [PATCH] doc: Remove explanation of "--" from several man pages
Date: Mon, 13 Nov 2017 13:15:07 +0900 [thread overview]
Message-ID: <xmqq8tfaak6s.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: <alpine.LFD.2.21.1711121600170.7904@localhost.localdomain> (Robert P. J. Day's message of "Sun, 12 Nov 2017 16:02:56 -0500 (EST)")
"Robert P. J. Day" <rpjday@crashcourse.ca> writes:
> There is no value in individual man pages explaining the purpose of
> the "--" separator.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
> ---
>
> unless every man page explains that option, it's pointless to have
> just *some* man pages explaining it, so might as well remove it from
> all of them.
Please do not remove diffstat that format-patch gave you at this
point. While commenting on the hunk on "git add", I wanted to see
if you touched "git rm", and the diffstat at front _is_ the go-to
place to do so for reviewers.
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index b700beaff..69d625285 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -180,11 +180,6 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files.
> bit is only changed in the index, the files on disk are left
> unchanged.
>
> -\--::
> - This option can be used to separate command-line options from
> - the list of files, (useful when filenames might be mistaken
> - for command-line options).
> -
I do not think if this removal alone is a good idea.
Before this can happen, the description for "--" in other pages,
(like gitcli(7), may need to be extended. Right now, gitcli's
mention of "--" is only about turning off disambiguation between
revs and pathspecs, and it does not cover this case
$ >./--foo-bar
$ git add -- --foo-bar
even though the description you are removing would have helped the
reader to understand why "--" is there. The hunk on "git rm" shares
the same issue.
> Configuration
> -------------
> diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
> index aa3b2bf2f..0ae2523e0 100644
> --- a/Documentation/git-check-attr.txt
> +++ b/Documentation/git-check-attr.txt
> @@ -36,10 +36,6 @@ OPTIONS
> If `--stdin` is also given, input paths are separated
> with a NUL character instead of a linefeed character.
>
> -\--::
> - Interpret all preceding arguments as attributes and all following
> - arguments as path names.
> -
This also has a similar issue. "--" here is not between revs and
pathspecs but is between attributes and pathspecs.
> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index d153c17e0..93ebb020c 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -171,9 +171,6 @@ Both the <eolinfo> in the index ("i/<eolinfo>")
> and in the working tree ("w/<eolinfo>") are shown for regular files,
> followed by the ("attr/<eolattr>").
>
> -\--::
> - Do not interpret any more arguments as options.
These removals would become a good idea, once we say that we would
use "--" to mean "you will not see any --flags after this point" (as
commonly seen in programs that are not Git) somewhere central like
gitcli(7).
next prev parent reply other threads:[~2017-11-13 4:15 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-11-12 21:02 [PATCH] doc: Remove explanation of "--" from several man pages Robert P. J. Day
2017-11-13 4:15 ` Junio C Hamano [this message]
2017-11-13 9:22 ` Robert P. J. Day
2017-11-13 9:48 ` Junio C Hamano
2017-11-13 9:56 ` Robert P. J. Day
Reply instructions:
You may reply publicly 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=xmqq8tfaak6s.fsf@gitster.mtv.corp.google.com \
--to=gitster@pobox.com \
--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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).