From: Junio C Hamano <gitster@pobox.com>
To: "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, "Martin Ågren" <martin.agren@gmail.com>,
"Alex Henrie" <alexhenrie24@gmail.com>,
"Philippe Blain" <levraiphilippeblain@gmail.com>
Subject: Re: [PATCH] doc: log takes multiple revision ranges
Date: Sat, 28 Mar 2020 18:34:14 -0700 [thread overview]
Message-ID: <xmqqd08wc5bd.fsf@gitster.c.googlers.com> (raw)
In-Reply-To: <pull.590.git.1585429894378.gitgitgadget@gmail.com> (Philippe Blain via GitGitGadget's message of "Sat, 28 Mar 2020 21:11:34 +0000")
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> `git log` accepts multiple revision ranges, but makes no mention of that
> in its documentation. Currently readers have to go to the `git
> rev-list` documentation to discover this useful feature.
I have a mixed feeling about this change. Surely you can write
git log v1.0..v2.0 v4.0..v5.0 -- Makefile
and you can explain that the command appears to take two "ranges",
but I do not think we want to encourage it to those who do not
understand what the above actually *means*.
Specifially, it does *NOT* list commits between v1.0 and v2.0, or
between v4.0 and v5.0, that touch the path Makefile. In other
words, you didn't really give two ranges with the syntax. What the
A..B notation means could be called a range, only when it appears
alone.
And we have *no* intention of changing the semantics.
"A..B" is a mere short-hand for ^A B, and it may appear to be a
range, but "A..B C..D" does not make "two ranges". It still merely
is a short-hand for ^A B ^C D, and if C reaches A and B (in the
above example, v4.0 is very likely to reach both v1.0 and v2.0), it
means the same thing as "C..D", i.e. "git log v4.0..v5.0 -- Makefile".
So I have a mildly strong opinion against the change to the synopsys
and the short-help; it is a bad change that does not help users. If
there are not sufficient explanation on the equivalence between A..B
and ^A B on "git log" documentation but there is one elsewhere, adding
a reference to help users learn is very much appreciated, though, and
I initially was hoping that the second hunk of this patch was such a
change, but it appears that it is not (it just adds the misleading
"you can have more than one" without making readers aware of what it
means to write "A..B C..D").
Thanks.
next prev parent reply other threads:[~2020-03-29 1:34 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-03-28 21:11 [PATCH] doc: log takes multiple revision ranges Philippe Blain via GitGitGadget
2020-03-29 1:34 ` Junio C Hamano [this message]
2020-03-30 12:52 ` Philippe Blain
2020-03-30 17:09 ` Junio C Hamano
2020-07-05 20:42 ` Philip Oakley
2020-07-07 13:08 ` Philippe Blain
2020-03-31 21:53 ` Taylor Blau
2020-07-03 3:38 ` [PATCH v2 0/4] doc: include git rev-list description in git log doc Philippe Blain via GitGitGadget
2020-07-03 3:38 ` [PATCH v2 1/4] git-log.txt: add links to 'rev-list' and 'diff' docs Philippe Blain via GitGitGadget
2020-07-07 0:55 ` Junio C Hamano
2020-07-07 13:11 ` Philippe Blain
2020-07-03 3:38 ` [PATCH v2 2/4] git-rev-list.txt: move description to separate file Philippe Blain via GitGitGadget
2020-07-03 3:38 ` [PATCH v2 3/4] git-log.txt: include rev-list-description.txt Philippe Blain via GitGitGadget
2020-07-03 3:38 ` [PATCH v2 4/4] rev-list-description.txt: fix Asciidoc syntax Philippe Blain via GitGitGadget
2020-07-07 0:59 ` Junio C Hamano
2020-07-07 13:12 ` Philippe Blain
2020-07-09 2:16 ` [PATCH v3 0/6] doc: include git rev-list description in git log doc Philippe Blain via GitGitGadget
2020-07-09 2:16 ` [PATCH v3 1/6] git-log.txt: add links to 'rev-list' and 'diff' docs Philippe Blain via GitGitGadget
2020-07-09 2:16 ` [PATCH v3 2/6] revisions.txt: describe 'rev1 rev2 ...' meaning for ranges Philippe Blain via GitGitGadget
2020-07-09 2:16 ` [PATCH v3 3/6] git-rev-list.txt: fix Asciidoc syntax Philippe Blain via GitGitGadget
2020-07-09 2:16 ` [PATCH v3 4/6] git-rev-list.txt: tweak wording in set operations Philippe Blain via GitGitGadget
2020-07-09 2:16 ` [PATCH v3 5/6] git-rev-list.txt: move description to separate file Philippe Blain via GitGitGadget
2020-07-09 2:16 ` [PATCH v3 6/6] git-log.txt: include rev-list-description.txt Philippe Blain via GitGitGadget
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=xmqqd08wc5bd.fsf@gitster.c.googlers.com \
--to=gitster@pobox.com \
--cc=alexhenrie24@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=levraiphilippeblain@gmail.com \
--cc=martin.agren@gmail.com \
/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).