Re* [PATCH 5/7] git-log.txt: rewrite note on why "--" may be required
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:56:59
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Ramkumar Ramachandra [off-list ref] writes:
quoted hunk
In its current form, the note talks about separating options from "branch names" and "refnames" in the same sentence. This is entirely inaccurate, as <revision range> need not be a set of branch names or ref names. Rewrite it to use the word "revision range", to be consistent with the SYNOPSIS. Signed-off-by: Ramkumar Ramachandra <redacted> --- Documentation/git-log.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 9576695..a976534 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt@@ -77,8 +77,8 @@ produced by --stat etc. Simplification" below for details and other simplification modes. + -To prevent confusion with options and branch names, paths may need to -be prefixed with "\-- " to separate them from options or refnames. +Paths may need to be prefixed with "\-- " to separate them from +options or the revision range, when confusion arises. include::rev-list-options.txt[]
This is an explanation about an enumeration item:
[\--] <path>...::
which corresponds to this in the synopsis:
'git log' [<options>] [<revision range>] [[\--] <path>...]
But the synopsis looks incorrect to me. It insists that if you were
to write "--", you have to give at least one <path>.
It should be more like this [*1*]:
'git log' [<options>] [<revision range>] [--] [<path>...]
It may be better to split the item into two, keep the current
description of <path> under "<path>...::" heading, and have another
heading for "--::" that talks about the disambiguation. The "--"
disambiguator is not solely for "your path might be mistaken as a
revision without it", but also for "your revision might be mistaken
as a path", but both the old and the new text are fuzzy about the
reason what "confusion" it is cautioning the reader.
Formatting doubts aside, one thing I am not so happy about the
suggested patch below (would apply on top of the patches from this
series) is that the explanation of a double-dash requires
understanding of _both_ what <revision range> and <path>... means to
the command, but for a reader who has read this page from top, the
latter has not been explained yet. We could of course swap the
order and describe <path>... first and then "--", but that does not
sound quite right, either. It has to be between these two.
[Footnote]
*1* We have many instances like "[--quiet]" in Documentation; do we
need the backslash before these double-dash like "[\--]"?
Documentation/git-log.txt | 22 +++++++++++++++++-----
1 file changed, 17 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index a976534..f5746e4 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt@@ -9,7 +9,7 @@ git-log - Show commit logs SYNOPSIS -------- [verse] -'git log' [<options>] [<revision range>] [[\--] <path>...] +'git log' [<options>] [<revision range>] [--] [<path>...] DESCRIPTION -----------
@@ -71,14 +71,26 @@ produced by --stat etc. ways to spell <revision range>, see the "Specifying Ranges" section of linkgit:gitrevisions[7]. -[\--] <path>...:: +--:: + On the command line, arguments that specify revision range + come first and then paths (see the next item). A + double-dash can be used to mark the end of revision range + arguments when an argument can be otherwise ambiguous. ++ +For example, when there are a file called `master` and a branch with +the same name, what `git log master` means is unclear. It may be +asking for the whole history leading to the current commit (i.e. no +<revision range> is specified, defaulting to `HEAD`), limited to +commits that touch a single path `master`. Or it may be asking for +the whole history leading to the tip of `master`, without any path +limiting. The former can be spelled `git log -- master`, while the +latter can be spelled `git log master --`. + +<path>...:: Show only commits that are enough to explain how the files that match the specified paths came to be. See "History Simplification" below for details and other simplification modes. -+ -Paths may need to be prefixed with "\-- " to separate them from -options or the revision range, when confusion arises. include::rev-list-options.txt[]