Re: [PATCH] doc: Remove explanation of "--" from several man pages
On Mon, 13 Nov 2017, Junio C Hamano wrote:
Show 17 quoted lines
> "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.
apologies, won't happen again.
Show 27 quoted lines
> > 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.
i don't see the problem here ... in the above, "--foobar" is clearly
a pathspec. and if you think that's a special case that needs special
explanation, then that argument surely applies to several other
commands and their man pages.
the main point here is that it's inconsistent to have *some* man
pages explicitly explain "--" and not have *all* of them explain it.
either they all should, or none of them should, and there's little
value in suggesting that the occasional man page somehow deserves
special treatment.
Show 17 quoted lines
> > 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.
that can already be seen in the SYNOPSIS for that command, it does
not require further explanation:
SYNOPSIS
git check-attr [-a | --all | attr...] [--] pathname...Show 15 quoted lines
> > 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). if you want to suggest some wording to make that happen, that would
be great, but i'm standing by my opinion that there is no rationale
for *any* man page explaining what "--" means when, as far as i can
tell, it always means the same thing.
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================Robert P. J. Day <rpjday@crashcourse.ca>