Re* [PATCH 5/7] git-log.txt: rewrite note on why "--" may be required
Ramkumar Ramachandra <artagnon@gmail.com> writes:
Show 25 quoted lines
> 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 <artagnon@gmail.com>
> ---
> 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(-)
Show changes to Documentation/git-log.txt +17 −5
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[]
Ramkumar Ramachandra