* [PATCH v2 1/4] git-log.txt: add links to 'rev-list' and 'diff' docs
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 ` Philippe Blain via GitGitGadget
2020-07-07 0:55 ` Junio C Hamano
2020-07-03 3:38 ` [PATCH v2 2/4] git-rev-list.txt: move description to separate file Philippe Blain via GitGitGadget
` (3 subsequent siblings)
4 siblings, 1 reply; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-03 3:38 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Add links to the documentation for `git rev-list` and `git diff`
instead of simply mentioning them, to make it easier for readers to reach
these documentation pages. Let's link to `git diff` as this is the
porcelain command, and the rest of the family (`diff-index`, `diff-tree` and
`diff-files`) are mentioned in the "Raw output format" section of the
`git diff` documentation.
Signed-off-by: Philippe Blain <levraiphilippeblain@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 20e6d21a74..04ea18d1c0 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -15,9 +15,9 @@ DESCRIPTION
-----------
Shows the commit logs.
-The command takes options applicable to the `git rev-list`
+The command takes options applicable to the linkgit:git-rev-list[1]
command to control what is shown and how, and options applicable to
-the `git diff-*` commands to control how the changes
+the linkgit:git-diff[1] family of commands to control how the changes
each commit introduces are shown.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread
* Re: [PATCH v2 1/4] git-log.txt: add links to 'rev-list' and 'diff' docs
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
0 siblings, 1 reply; 23+ messages in thread
From: Junio C Hamano @ 2020-07-07 0:55 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Lawrence Siebert, Denton Liu, Taylor Blau, Philippe Blain
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> Add links to the documentation for `git rev-list` and `git diff`
> instead of simply mentioning them, to make it easier for readers to reach
> these documentation pages. Let's link to `git diff` as this is the
> porcelain command, and the rest of the family (`diff-index`, `diff-tree` and
> `diff-files`) are mentioned in the "Raw output format" section of the
> `git diff` documentation.
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@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 20e6d21a74..04ea18d1c0 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -15,9 +15,9 @@ DESCRIPTION
> -----------
> Shows the commit logs.
>
> -The command takes options applicable to the `git rev-list`
> +The command takes options applicable to the linkgit:git-rev-list[1]
> command to control what is shown and how, and options applicable to
> -the `git diff-*` commands to control how the changes
> +the linkgit:git-diff[1] family of commands to control how the changes
> each commit introduces are shown.
The original did mean "git diff-*" family of plumbing commands, but
I think it makes more sense these days to just refer to "git diff"
Porcelain, which is the single entry point everybody uses. So you
would probably want to further replace "family of commands" with
just "command" in the text.
Other than that, I think making these into links is a good idea.
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v2 1/4] git-log.txt: add links to 'rev-list' and 'diff' docs
2020-07-07 0:55 ` Junio C Hamano
@ 2020-07-07 13:11 ` Philippe Blain
0 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain @ 2020-07-07 13:11 UTC (permalink / raw)
To: Junio C Hamano
Cc: Philippe Blain via GitGitGadget, git, Lawrence Siebert,
Denton Liu, Taylor Blau
Hi Junio,
> Le 6 juil. 2020 à 20:55, Junio C Hamano <gitster@pobox.com> a écrit :
>
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>>
---8<---
>>
>> -The command takes options applicable to the `git rev-list`
>> +The command takes options applicable to the linkgit:git-rev-list[1]
>> command to control what is shown and how, and options applicable to
>> -the `git diff-*` commands to control how the changes
>> +the linkgit:git-diff[1] family of commands to control how the changes
>> each commit introduces are shown.
>
> The original did mean "git diff-*" family of plumbing commands, but
> I think it makes more sense these days to just refer to "git diff"
> Porcelain, which is the single entry point everybody uses. So you
> would probably want to further replace "family of commands" with
> just "command" in the text.
>
Right. I'll change that.
> Other than that, I think making these into links is a good idea.
Thanks,
Philippe.
P.S. sorry for the resend, I forgot to convert the message to plain text the first time...
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v2 2/4] git-rev-list.txt: move description to separate file
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-03 3:38 ` 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
` (2 subsequent siblings)
4 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-03 3:38 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
A following commit will reuse the description of the `git rev-list`
command in the `git log` manpage.
Move this description to a separate file.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-rev-list.txt | 39 +-------------------------
Documentation/rev-list-description.txt | 38 +++++++++++++++++++++++++
2 files changed, 39 insertions(+), 38 deletions(-)
create mode 100644 Documentation/rev-list-description.txt
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 025c911436..b06e11ae56 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -14,44 +14,7 @@ SYNOPSIS
DESCRIPTION
-----------
-List commits that are reachable by following the `parent` links from the
-given commit(s), but exclude commits that are reachable from the one(s)
-given with a '{caret}' in front of them. The output is given in reverse
-chronological order by default.
-
-You can think of this as a set operation. Commits given on the command
-line form a set of commits that are reachable from any of them, and then
-commits reachable from any of the ones given with '{caret}' in front are
-subtracted from that set. The remaining commits are what comes out in the
-command's output. Various other options and paths parameters can be used
-to further limit the result.
-
-Thus, the following command:
-
------------------------------------------------------------------------
- $ git rev-list foo bar ^baz
------------------------------------------------------------------------
-
-means "list all the commits which are reachable from 'foo' or 'bar', but
-not from 'baz'".
-
-A special notation "'<commit1>'..'<commit2>'" can be used as a
-short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
-the following may be used interchangeably:
-
------------------------------------------------------------------------
- $ git rev-list origin..HEAD
- $ git rev-list HEAD ^origin
------------------------------------------------------------------------
-
-Another special notation is "'<commit1>'...'<commit2>'" which is useful
-for merges. The resulting set of commits is the symmetric difference
-between the two operands. The following two commands are equivalent:
-
------------------------------------------------------------------------
- $ git rev-list A B --not $(git merge-base --all A B)
- $ git rev-list A...B
------------------------------------------------------------------------
+include::rev-list-description.txt[]
'rev-list' is a very essential Git command, since it
provides the ability to build and traverse commit ancestry graphs. For
diff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt
new file mode 100644
index 0000000000..aa6bbd8cec
--- /dev/null
+++ b/Documentation/rev-list-description.txt
@@ -0,0 +1,38 @@
+List commits that are reachable by following the `parent` links from the
+given commit(s), but exclude commits that are reachable from the one(s)
+given with a '{caret}' in front of them. The output is given in reverse
+chronological order by default.
+
+You can think of this as a set operation. Commits given on the command
+line form a set of commits that are reachable from any of them, and then
+commits reachable from any of the ones given with '{caret}' in front are
+subtracted from that set. The remaining commits are what comes out in the
+command's output. Various other options and paths parameters can be used
+to further limit the result.
+
+Thus, the following command:
+
+-----------------------------------------------------------------------
+ $ git rev-list foo bar ^baz
+-----------------------------------------------------------------------
+
+means "list all the commits which are reachable from 'foo' or 'bar', but
+not from 'baz'".
+
+A special notation "'<commit1>'..'<commit2>'" can be used as a
+short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
+the following may be used interchangeably:
+
+-----------------------------------------------------------------------
+ $ git rev-list origin..HEAD
+ $ git rev-list HEAD ^origin
+-----------------------------------------------------------------------
+
+Another special notation is "'<commit1>'...'<commit2>'" which is useful
+for merges. The resulting set of commits is the symmetric difference
+between the two operands. The following two commands are equivalent:
+
+-----------------------------------------------------------------------
+ $ git rev-list A B --not $(git merge-base --all A B)
+ $ git rev-list A...B
+-----------------------------------------------------------------------
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v2 3/4] git-log.txt: include rev-list-description.txt
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-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 ` 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-09 2:16 ` [PATCH v3 0/6] doc: include git rev-list description in git log doc Philippe Blain via GitGitGadget
4 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-03 3:38 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The `git log` synopsis mentions `<revision range>`, and the description
of this option links to gitrevisions(7), but a nice explanation of
how a revision range can be constructed from individual commits,
optionnally prefixed with `^`, also exists in `rev-list-description.txt`.
Include this description in the man page for `git log`.
Add Asciidoc 'ifdef's to `rev-list-description.txt` so that either `git
rev-list` or `git log` appears in the respective man pages.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-log.txt | 3 +++
Documentation/git-rev-list.txt | 1 +
Documentation/rev-list-description.txt | 23 +++++++++++++++++++++++
3 files changed, 27 insertions(+)
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 04ea18d1c0..d34d101255 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -15,6 +15,9 @@ DESCRIPTION
-----------
Shows the commit logs.
+:git-log: 1
+include::rev-list-description.txt[]
+
The command takes options applicable to the linkgit:git-rev-list[1]
command to control what is shown and how, and options applicable to
the linkgit:git-diff[1] family of commands to control how the changes
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index b06e11ae56..5da66232dc 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -14,6 +14,7 @@ SYNOPSIS
DESCRIPTION
-----------
+:git-rev-list: 1
include::rev-list-description.txt[]
'rev-list' is a very essential Git command, since it
diff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt
index aa6bbd8cec..dce78561be 100644
--- a/Documentation/rev-list-description.txt
+++ b/Documentation/rev-list-description.txt
@@ -12,9 +12,16 @@ to further limit the result.
Thus, the following command:
+ifdef::git-rev-list[]
-----------------------------------------------------------------------
$ git rev-list foo bar ^baz
-----------------------------------------------------------------------
+endif::git-rev-list[]
+ifdef::git-log[]
+-----------------------------------------------------------------------
+ $ git log foo bar ^baz
+-----------------------------------------------------------------------
+endif::git-log[]
means "list all the commits which are reachable from 'foo' or 'bar', but
not from 'baz'".
@@ -23,16 +30,32 @@ A special notation "'<commit1>'..'<commit2>'" can be used as a
short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
the following may be used interchangeably:
+ifdef::git-rev-list[]
-----------------------------------------------------------------------
$ git rev-list origin..HEAD
$ git rev-list HEAD ^origin
-----------------------------------------------------------------------
+endif::git-rev-list[]
+ifdef::git-log[]
+-----------------------------------------------------------------------
+ $ git log origin..HEAD
+ $ git log HEAD ^origin
+-----------------------------------------------------------------------
+endif::git-log[]
Another special notation is "'<commit1>'...'<commit2>'" which is useful
for merges. The resulting set of commits is the symmetric difference
between the two operands. The following two commands are equivalent:
+ifdef::git-rev-list[]
-----------------------------------------------------------------------
$ git rev-list A B --not $(git merge-base --all A B)
$ git rev-list A...B
-----------------------------------------------------------------------
+endif::git-rev-list[]
+ifdef::git-log[]
+-----------------------------------------------------------------------
+ $ git log A B --not $(git merge-base --all A B)
+ $ git log A...B
+-----------------------------------------------------------------------
+endif::git-log[]
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v2 4/4] rev-list-description.txt: fix Asciidoc syntax
2020-07-03 3:38 ` [PATCH v2 0/4] doc: include git rev-list description in git log doc Philippe Blain via GitGitGadget
` (2 preceding siblings ...)
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 ` Philippe Blain via GitGitGadget
2020-07-07 0:59 ` Junio C Hamano
2020-07-09 2:16 ` [PATCH v3 0/6] doc: include git rev-list description in git log doc Philippe Blain via GitGitGadget
4 siblings, 1 reply; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-03 3:38 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Using '{caret}' inside double quotes and immediately following with a
single quoted word does not create the desired output: '<commit1>'
appears verbatim instead of being emphasized.
Use a litteral caret ('^') instead.
Also, remove the leading tabs in shell examples to bring them more in
line with the rest of the documentation.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/rev-list-description.txt | 22 +++++++++++-----------
1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt
index dce78561be..4bde2fd4fe 100644
--- a/Documentation/rev-list-description.txt
+++ b/Documentation/rev-list-description.txt
@@ -14,12 +14,12 @@ Thus, the following command:
ifdef::git-rev-list[]
-----------------------------------------------------------------------
- $ git rev-list foo bar ^baz
+$ git rev-list foo bar ^baz
-----------------------------------------------------------------------
endif::git-rev-list[]
ifdef::git-log[]
-----------------------------------------------------------------------
- $ git log foo bar ^baz
+$ git log foo bar ^baz
-----------------------------------------------------------------------
endif::git-log[]
@@ -27,19 +27,19 @@ means "list all the commits which are reachable from 'foo' or 'bar', but
not from 'baz'".
A special notation "'<commit1>'..'<commit2>'" can be used as a
-short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
+short-hand for "^'<commit1>' '<commit2>'". For example, either of
the following may be used interchangeably:
ifdef::git-rev-list[]
-----------------------------------------------------------------------
- $ git rev-list origin..HEAD
- $ git rev-list HEAD ^origin
+$ git rev-list origin..HEAD
+$ git rev-list HEAD ^origin
-----------------------------------------------------------------------
endif::git-rev-list[]
ifdef::git-log[]
-----------------------------------------------------------------------
- $ git log origin..HEAD
- $ git log HEAD ^origin
+$ git log origin..HEAD
+$ git log HEAD ^origin
-----------------------------------------------------------------------
endif::git-log[]
@@ -49,13 +49,13 @@ between the two operands. The following two commands are equivalent:
ifdef::git-rev-list[]
-----------------------------------------------------------------------
- $ git rev-list A B --not $(git merge-base --all A B)
- $ git rev-list A...B
+$ git rev-list A B --not $(git merge-base --all A B)
+$ git rev-list A...B
-----------------------------------------------------------------------
endif::git-rev-list[]
ifdef::git-log[]
-----------------------------------------------------------------------
- $ git log A B --not $(git merge-base --all A B)
- $ git log A...B
+$ git log A B --not $(git merge-base --all A B)
+$ git log A...B
-----------------------------------------------------------------------
endif::git-log[]
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread
* Re: [PATCH v2 4/4] rev-list-description.txt: fix Asciidoc syntax
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
0 siblings, 1 reply; 23+ messages in thread
From: Junio C Hamano @ 2020-07-07 0:59 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Lawrence Siebert, Denton Liu, Taylor Blau, Philippe Blain
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> Using '{caret}' inside double quotes and immediately following with a
> single quoted word does not create the desired output: '<commit1>'
> appears verbatim instead of being emphasized.
>
> Use a litteral caret ('^') instead.
>
> Also, remove the leading tabs in shell examples to bring them more in
> line with the rest of the documentation.
These should be done _before_ 2/4 as a preliminary clean-up, I
think.
Thanks for a pleasant read.
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [PATCH v2 4/4] rev-list-description.txt: fix Asciidoc syntax
2020-07-07 0:59 ` Junio C Hamano
@ 2020-07-07 13:12 ` Philippe Blain
0 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain @ 2020-07-07 13:12 UTC (permalink / raw)
To: Junio C Hamano
Cc: Philippe Blain via GitGitGadget, git, Lawrence Siebert,
Denton Liu, Taylor Blau
> Le 6 juil. 2020 à 20:59, Junio C Hamano <gitster@pobox.com> a écrit :
>
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>>
>> Using '{caret}' inside double quotes and immediately following with a
>> single quoted word does not create the desired output: '<commit1>'
>> appears verbatim instead of being emphasized.
>>
>> Use a litteral caret ('^') instead.
>>
>> Also, remove the leading tabs in shell examples to bring them more in
>> line with the rest of the documentation.
>
> These should be done _before_ 2/4 as a preliminary clean-up, I
> think.
I agree. I'll reorder that for v3.
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v3 0/6] doc: include git rev-list description in git log doc
2020-07-03 3:38 ` [PATCH v2 0/4] doc: include git rev-list description in git log doc Philippe Blain via GitGitGadget
` (3 preceding siblings ...)
2020-07-03 3:38 ` [PATCH v2 4/4] rev-list-description.txt: fix Asciidoc syntax Philippe Blain via GitGitGadget
@ 2020-07-09 2:16 ` 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
` (5 more replies)
4 siblings, 6 replies; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-09 2:16 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philip Oakley, Philippe Blain
Changes since v2:
* applied Junio's suggestions
* added a preparatory commit tweaking the wording of one sentence in the
git rev-list description
* added a new commit adding a sentence in revisions.txt to mention
explicitly what it means to list several revisions to form a range.
v2: This series moves the nice explanation in the 'Description' section of
the git rev-list man page to a separate file and includes this file in the
git log man page.
This goal is to make readers more aware that they can write e.g.
git log branch1 branch2 branch3 branch4 --not master
to see commits on each of branch1-4, that are not on master, since this is
not immediately obvious (at least to me) in the git log man page.
Note that I made several commits for ease of reviewing, I'll squash some if
this would be preferred.
Changes since v1: took a completely different approach following the
comments received from Junio and Taylor.
Philippe Blain (6):
git-log.txt: add links to 'rev-list' and 'diff' docs
revisions.txt: describe 'rev1 rev2 ...' meaning for ranges
git-rev-list.txt: fix Asciidoc syntax
git-rev-list.txt: tweak wording in set operations
git-rev-list.txt: move description to separate file
git-log.txt: include rev-list-description.txt
Documentation/git-log.txt | 7 ++-
Documentation/git-rev-list.txt | 40 +----------------
Documentation/rev-list-description.txt | 61 ++++++++++++++++++++++++++
Documentation/revisions.txt | 3 ++
4 files changed, 71 insertions(+), 40 deletions(-)
create mode 100644 Documentation/rev-list-description.txt
base-commit: a08a83db2bf27f015bec9a435f6d73e223c21c5e
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-590%2Fphil-blain%2Fdoc-log-multiple-ranges-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-590/phil-blain/doc-log-multiple-ranges-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/590
Range-diff vs v2:
1: 59c48282a0 ! 1: 59027b0f6a git-log.txt: add links to 'rev-list' and 'diff' docs
@@ Documentation/git-log.txt: DESCRIPTION
+The command takes options applicable to the linkgit:git-rev-list[1]
command to control what is shown and how, and options applicable to
-the `git diff-*` commands to control how the changes
-+the linkgit:git-diff[1] family of commands to control how the changes
++the linkgit:git-diff[1] command to control how the changes
each commit introduces are shown.
-: ---------- > 2: 3c573695a8 revisions.txt: describe 'rev1 rev2 ...' meaning for ranges
4: 3b923780c1 ! 3: b8ee4a743c rev-list-description.txt: fix Asciidoc syntax
@@ Metadata
Author: Philippe Blain <levraiphilippeblain@gmail.com>
## Commit message ##
- rev-list-description.txt: fix Asciidoc syntax
+ git-rev-list.txt: fix Asciidoc syntax
Using '{caret}' inside double quotes and immediately following with a
single quoted word does not create the desired output: '<commit1>'
@@ Commit message
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
- ## Documentation/rev-list-description.txt ##
-@@ Documentation/rev-list-description.txt: Thus, the following command:
+ ## Documentation/git-rev-list.txt ##
+@@ Documentation/git-rev-list.txt: to further limit the result.
+ Thus, the following command:
- ifdef::git-rev-list[]
-----------------------------------------------------------------------
- $ git rev-list foo bar ^baz
+$ git rev-list foo bar ^baz
-----------------------------------------------------------------------
- endif::git-rev-list[]
- ifdef::git-log[]
- -----------------------------------------------------------------------
-- $ git log foo bar ^baz
-+$ git log foo bar ^baz
- -----------------------------------------------------------------------
- endif::git-log[]
-@@ Documentation/rev-list-description.txt: means "list all the commits which are reachable from 'foo' or 'bar', but
+ means "list all the commits which are reachable from 'foo' or 'bar', but
not from 'baz'".
A special notation "'<commit1>'..'<commit2>'" can be used as a
@@ Documentation/rev-list-description.txt: means "list all the commits which are re
+short-hand for "^'<commit1>' '<commit2>'". For example, either of
the following may be used interchangeably:
- ifdef::git-rev-list[]
-----------------------------------------------------------------------
- $ git rev-list origin..HEAD
- $ git rev-list HEAD ^origin
+$ git rev-list origin..HEAD
+$ git rev-list HEAD ^origin
-----------------------------------------------------------------------
- endif::git-rev-list[]
- ifdef::git-log[]
- -----------------------------------------------------------------------
-- $ git log origin..HEAD
-- $ git log HEAD ^origin
-+$ git log origin..HEAD
-+$ git log HEAD ^origin
- -----------------------------------------------------------------------
- endif::git-log[]
-@@ Documentation/rev-list-description.txt: between the two operands. The following two commands are equivalent:
+ Another special notation is "'<commit1>'...'<commit2>'" which is useful
+@@ Documentation/git-rev-list.txt: for merges. The resulting set of commits is the symmetric difference
+ between the two operands. The following two commands are equivalent:
- ifdef::git-rev-list[]
-----------------------------------------------------------------------
- $ git rev-list A B --not $(git merge-base --all A B)
- $ git rev-list A...B
+$ git rev-list A B --not $(git merge-base --all A B)
+$ git rev-list A...B
-----------------------------------------------------------------------
- endif::git-rev-list[]
- ifdef::git-log[]
- -----------------------------------------------------------------------
-- $ git log A B --not $(git merge-base --all A B)
-- $ git log A...B
-+$ git log A B --not $(git merge-base --all A B)
-+$ git log A...B
- -----------------------------------------------------------------------
- endif::git-log[]
+
+ 'rev-list' is a very essential Git command, since it
-: ---------- > 4: cf934ddf33 git-rev-list.txt: tweak wording in set operations
2: daf00d9398 ! 5: f61bbb57cb git-rev-list.txt: move description to separate file
@@ Documentation/git-rev-list.txt: SYNOPSIS
-given with a '{caret}' in front of them. The output is given in reverse
-chronological order by default.
-
--You can think of this as a set operation. Commits given on the command
--line form a set of commits that are reachable from any of them, and then
--commits reachable from any of the ones given with '{caret}' in front are
--subtracted from that set. The remaining commits are what comes out in the
--command's output. Various other options and paths parameters can be used
--to further limit the result.
+-You can think of this as a set operation. Commits reachable from any of
+-the commits given on the command line form a set, and then commits reachable
+-from any of the ones given with '{caret}' in front are subtracted from that
+-set. The remaining commits are what comes out in the command's output.
+-Various other options and paths parameters can be used to further limit the
+-result.
-
-Thus, the following command:
-
------------------------------------------------------------------------
-- $ git rev-list foo bar ^baz
+-$ git rev-list foo bar ^baz
------------------------------------------------------------------------
-
-means "list all the commits which are reachable from 'foo' or 'bar', but
-not from 'baz'".
-
-A special notation "'<commit1>'..'<commit2>'" can be used as a
--short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
+-short-hand for "^'<commit1>' '<commit2>'". For example, either of
-the following may be used interchangeably:
-
------------------------------------------------------------------------
-- $ git rev-list origin..HEAD
-- $ git rev-list HEAD ^origin
+-$ git rev-list origin..HEAD
+-$ git rev-list HEAD ^origin
------------------------------------------------------------------------
-
-Another special notation is "'<commit1>'...'<commit2>'" which is useful
@@ Documentation/git-rev-list.txt: SYNOPSIS
-between the two operands. The following two commands are equivalent:
-
------------------------------------------------------------------------
-- $ git rev-list A B --not $(git merge-base --all A B)
-- $ git rev-list A...B
+-$ git rev-list A B --not $(git merge-base --all A B)
+-$ git rev-list A...B
------------------------------------------------------------------------
+include::rev-list-description.txt[]
@@ Documentation/rev-list-description.txt (new)
+given with a '{caret}' in front of them. The output is given in reverse
+chronological order by default.
+
-+You can think of this as a set operation. Commits given on the command
-+line form a set of commits that are reachable from any of them, and then
-+commits reachable from any of the ones given with '{caret}' in front are
-+subtracted from that set. The remaining commits are what comes out in the
-+command's output. Various other options and paths parameters can be used
-+to further limit the result.
++You can think of this as a set operation. Commits reachable from any of
++the commits given on the command line form a set, and then commits reachable
++from any of the ones given with '{caret}' in front are subtracted from that
++set. The remaining commits are what comes out in the command's output.
++Various other options and paths parameters can be used to further limit the
++result.
+
+Thus, the following command:
+
+-----------------------------------------------------------------------
-+ $ git rev-list foo bar ^baz
++$ git rev-list foo bar ^baz
+-----------------------------------------------------------------------
+
+means "list all the commits which are reachable from 'foo' or 'bar', but
+not from 'baz'".
+
+A special notation "'<commit1>'..'<commit2>'" can be used as a
-+short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
++short-hand for "^'<commit1>' '<commit2>'". For example, either of
+the following may be used interchangeably:
+
+-----------------------------------------------------------------------
-+ $ git rev-list origin..HEAD
-+ $ git rev-list HEAD ^origin
++$ git rev-list origin..HEAD
++$ git rev-list HEAD ^origin
+-----------------------------------------------------------------------
+
+Another special notation is "'<commit1>'...'<commit2>'" which is useful
@@ Documentation/rev-list-description.txt (new)
+between the two operands. The following two commands are equivalent:
+
+-----------------------------------------------------------------------
-+ $ git rev-list A B --not $(git merge-base --all A B)
-+ $ git rev-list A...B
++$ git rev-list A B --not $(git merge-base --all A B)
++$ git rev-list A...B
+-----------------------------------------------------------------------
3: eeaf4fe5dc ! 6: d04b6c62a3 git-log.txt: include rev-list-description.txt
@@ Documentation/git-log.txt: DESCRIPTION
+
The command takes options applicable to the linkgit:git-rev-list[1]
command to control what is shown and how, and options applicable to
- the linkgit:git-diff[1] family of commands to control how the changes
+ the linkgit:git-diff[1] command to control how the changes
## Documentation/git-rev-list.txt ##
@@ Documentation/git-rev-list.txt: SYNOPSIS
@@ Documentation/git-rev-list.txt: SYNOPSIS
'rev-list' is a very essential Git command, since it
## Documentation/rev-list-description.txt ##
-@@ Documentation/rev-list-description.txt: to further limit the result.
+@@ Documentation/rev-list-description.txt: result.
Thus, the following command:
+ifdef::git-rev-list[]
-----------------------------------------------------------------------
- $ git rev-list foo bar ^baz
+ $ git rev-list foo bar ^baz
-----------------------------------------------------------------------
+endif::git-rev-list[]
+ifdef::git-log[]
+-----------------------------------------------------------------------
-+ $ git log foo bar ^baz
++$ git log foo bar ^baz
+-----------------------------------------------------------------------
+endif::git-log[]
means "list all the commits which are reachable from 'foo' or 'bar', but
not from 'baz'".
@@ Documentation/rev-list-description.txt: A special notation "'<commit1>'..'<commit2>'" can be used as a
- short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
+ short-hand for "^'<commit1>' '<commit2>'". For example, either of
the following may be used interchangeably:
+ifdef::git-rev-list[]
-----------------------------------------------------------------------
- $ git rev-list origin..HEAD
- $ git rev-list HEAD ^origin
+ $ git rev-list origin..HEAD
+ $ git rev-list HEAD ^origin
-----------------------------------------------------------------------
+endif::git-rev-list[]
+ifdef::git-log[]
+-----------------------------------------------------------------------
-+ $ git log origin..HEAD
-+ $ git log HEAD ^origin
++$ git log origin..HEAD
++$ git log HEAD ^origin
+-----------------------------------------------------------------------
+endif::git-log[]
@@ Documentation/rev-list-description.txt: A special notation "'<commit1>'..'<commi
+ifdef::git-rev-list[]
-----------------------------------------------------------------------
- $ git rev-list A B --not $(git merge-base --all A B)
- $ git rev-list A...B
+ $ git rev-list A B --not $(git merge-base --all A B)
+ $ git rev-list A...B
-----------------------------------------------------------------------
+endif::git-rev-list[]
+ifdef::git-log[]
+-----------------------------------------------------------------------
-+ $ git log A B --not $(git merge-base --all A B)
-+ $ git log A...B
++$ git log A B --not $(git merge-base --all A B)
++$ git log A...B
+-----------------------------------------------------------------------
+endif::git-log[]
--
gitgitgadget
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v3 1/6] git-log.txt: add links to 'rev-list' and 'diff' docs
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 ` 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
` (4 subsequent siblings)
5 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-09 2:16 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philip Oakley, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Add links to the documentation for `git rev-list` and `git diff`
instead of simply mentioning them, to make it easier for readers to reach
these documentation pages. Let's link to `git diff` as this is the
porcelain command, and the rest of the family (`diff-index`, `diff-tree` and
`diff-files`) are mentioned in the "Raw output format" section of the
`git diff` documentation.
Signed-off-by: Philippe Blain <levraiphilippeblain@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 20e6d21a74..0fcaf34d62 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -15,9 +15,9 @@ DESCRIPTION
-----------
Shows the commit logs.
-The command takes options applicable to the `git rev-list`
+The command takes options applicable to the linkgit:git-rev-list[1]
command to control what is shown and how, and options applicable to
-the `git diff-*` commands to control how the changes
+the linkgit:git-diff[1] command to control how the changes
each commit introduces are shown.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v3 2/6] revisions.txt: describe 'rev1 rev2 ...' meaning for ranges
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 ` Philippe Blain via GitGitGadget
2020-07-09 2:16 ` [PATCH v3 3/6] git-rev-list.txt: fix Asciidoc syntax Philippe Blain via GitGitGadget
` (3 subsequent siblings)
5 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-09 2:16 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philip Oakley, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The "Specifying ranges" section does not mention explicitly that
several commits can be specified to form a range.
Add a mention to that effect.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/revisions.txt | 3 +++
1 file changed, 3 insertions(+)
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 1ad95065c1..d9169c062e 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -254,6 +254,9 @@ specifying a single revision, using the notation described in the
previous section, means the set of commits `reachable` from the given
commit.
+Specifying several revisions means the set of commits reachable from
+any of the given commits.
+
A commit's reachable set is the commit itself and the commits in
its ancestry chain.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v3 3/6] git-rev-list.txt: fix Asciidoc syntax
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 ` 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
` (2 subsequent siblings)
5 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-09 2:16 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philip Oakley, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Using '{caret}' inside double quotes and immediately following with a
single quoted word does not create the desired output: '<commit1>'
appears verbatim instead of being emphasized.
Use a litteral caret ('^') instead.
Also, remove the leading tabs in shell examples to bring them more in
line with the rest of the documentation.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-rev-list.txt | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 025c911436..aa95334a79 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -29,19 +29,19 @@ to further limit the result.
Thus, the following command:
-----------------------------------------------------------------------
- $ git rev-list foo bar ^baz
+$ git rev-list foo bar ^baz
-----------------------------------------------------------------------
means "list all the commits which are reachable from 'foo' or 'bar', but
not from 'baz'".
A special notation "'<commit1>'..'<commit2>'" can be used as a
-short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
+short-hand for "^'<commit1>' '<commit2>'". For example, either of
the following may be used interchangeably:
-----------------------------------------------------------------------
- $ git rev-list origin..HEAD
- $ git rev-list HEAD ^origin
+$ git rev-list origin..HEAD
+$ git rev-list HEAD ^origin
-----------------------------------------------------------------------
Another special notation is "'<commit1>'...'<commit2>'" which is useful
@@ -49,8 +49,8 @@ for merges. The resulting set of commits is the symmetric difference
between the two operands. The following two commands are equivalent:
-----------------------------------------------------------------------
- $ git rev-list A B --not $(git merge-base --all A B)
- $ git rev-list A...B
+$ git rev-list A B --not $(git merge-base --all A B)
+$ git rev-list A...B
-----------------------------------------------------------------------
'rev-list' is a very essential Git command, since it
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v3 4/6] git-rev-list.txt: tweak wording in set operations
2020-07-09 2:16 ` [PATCH v3 0/6] doc: include git rev-list description in git log doc Philippe Blain via GitGitGadget
` (2 preceding siblings ...)
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 ` 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
5 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-09 2:16 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philip Oakley, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Tweak a sentence to make it a little more readable.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-rev-list.txt | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index aa95334a79..f2b83df2fa 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -19,12 +19,12 @@ given commit(s), but exclude commits that are reachable from the one(s)
given with a '{caret}' in front of them. The output is given in reverse
chronological order by default.
-You can think of this as a set operation. Commits given on the command
-line form a set of commits that are reachable from any of them, and then
-commits reachable from any of the ones given with '{caret}' in front are
-subtracted from that set. The remaining commits are what comes out in the
-command's output. Various other options and paths parameters can be used
-to further limit the result.
+You can think of this as a set operation. Commits reachable from any of
+the commits given on the command line form a set, and then commits reachable
+from any of the ones given with '{caret}' in front are subtracted from that
+set. The remaining commits are what comes out in the command's output.
+Various other options and paths parameters can be used to further limit the
+result.
Thus, the following command:
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v3 5/6] git-rev-list.txt: move description to separate file
2020-07-09 2:16 ` [PATCH v3 0/6] doc: include git rev-list description in git log doc Philippe Blain via GitGitGadget
` (3 preceding siblings ...)
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 ` 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
5 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-09 2:16 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philip Oakley, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
A following commit will reuse the description of the `git rev-list`
command in the `git log` manpage.
Move this description to a separate file.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-rev-list.txt | 39 +-------------------------
Documentation/rev-list-description.txt | 38 +++++++++++++++++++++++++
2 files changed, 39 insertions(+), 38 deletions(-)
create mode 100644 Documentation/rev-list-description.txt
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index f2b83df2fa..b06e11ae56 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -14,44 +14,7 @@ SYNOPSIS
DESCRIPTION
-----------
-List commits that are reachable by following the `parent` links from the
-given commit(s), but exclude commits that are reachable from the one(s)
-given with a '{caret}' in front of them. The output is given in reverse
-chronological order by default.
-
-You can think of this as a set operation. Commits reachable from any of
-the commits given on the command line form a set, and then commits reachable
-from any of the ones given with '{caret}' in front are subtracted from that
-set. The remaining commits are what comes out in the command's output.
-Various other options and paths parameters can be used to further limit the
-result.
-
-Thus, the following command:
-
------------------------------------------------------------------------
-$ git rev-list foo bar ^baz
------------------------------------------------------------------------
-
-means "list all the commits which are reachable from 'foo' or 'bar', but
-not from 'baz'".
-
-A special notation "'<commit1>'..'<commit2>'" can be used as a
-short-hand for "^'<commit1>' '<commit2>'". For example, either of
-the following may be used interchangeably:
-
------------------------------------------------------------------------
-$ git rev-list origin..HEAD
-$ git rev-list HEAD ^origin
------------------------------------------------------------------------
-
-Another special notation is "'<commit1>'...'<commit2>'" which is useful
-for merges. The resulting set of commits is the symmetric difference
-between the two operands. The following two commands are equivalent:
-
------------------------------------------------------------------------
-$ git rev-list A B --not $(git merge-base --all A B)
-$ git rev-list A...B
------------------------------------------------------------------------
+include::rev-list-description.txt[]
'rev-list' is a very essential Git command, since it
provides the ability to build and traverse commit ancestry graphs. For
diff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt
new file mode 100644
index 0000000000..14d78b91aa
--- /dev/null
+++ b/Documentation/rev-list-description.txt
@@ -0,0 +1,38 @@
+List commits that are reachable by following the `parent` links from the
+given commit(s), but exclude commits that are reachable from the one(s)
+given with a '{caret}' in front of them. The output is given in reverse
+chronological order by default.
+
+You can think of this as a set operation. Commits reachable from any of
+the commits given on the command line form a set, and then commits reachable
+from any of the ones given with '{caret}' in front are subtracted from that
+set. The remaining commits are what comes out in the command's output.
+Various other options and paths parameters can be used to further limit the
+result.
+
+Thus, the following command:
+
+-----------------------------------------------------------------------
+$ git rev-list foo bar ^baz
+-----------------------------------------------------------------------
+
+means "list all the commits which are reachable from 'foo' or 'bar', but
+not from 'baz'".
+
+A special notation "'<commit1>'..'<commit2>'" can be used as a
+short-hand for "^'<commit1>' '<commit2>'". For example, either of
+the following may be used interchangeably:
+
+-----------------------------------------------------------------------
+$ git rev-list origin..HEAD
+$ git rev-list HEAD ^origin
+-----------------------------------------------------------------------
+
+Another special notation is "'<commit1>'...'<commit2>'" which is useful
+for merges. The resulting set of commits is the symmetric difference
+between the two operands. The following two commands are equivalent:
+
+-----------------------------------------------------------------------
+$ git rev-list A B --not $(git merge-base --all A B)
+$ git rev-list A...B
+-----------------------------------------------------------------------
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread
* [PATCH v3 6/6] git-log.txt: include rev-list-description.txt
2020-07-09 2:16 ` [PATCH v3 0/6] doc: include git rev-list description in git log doc Philippe Blain via GitGitGadget
` (4 preceding siblings ...)
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 ` Philippe Blain via GitGitGadget
5 siblings, 0 replies; 23+ messages in thread
From: Philippe Blain via GitGitGadget @ 2020-07-09 2:16 UTC (permalink / raw)
To: git
Cc: Lawrence Siebert, Denton Liu, Junio C Hamano, Taylor Blau,
Philip Oakley, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The `git log` synopsis mentions `<revision range>`, and the description
of this option links to gitrevisions(7), but a nice explanation of
how a revision range can be constructed from individual commits,
optionnally prefixed with `^`, also exists in `rev-list-description.txt`.
Include this description in the man page for `git log`.
Add Asciidoc 'ifdef's to `rev-list-description.txt` so that either `git
rev-list` or `git log` appears in the respective man pages.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-log.txt | 3 +++
Documentation/git-rev-list.txt | 1 +
Documentation/rev-list-description.txt | 23 +++++++++++++++++++++++
3 files changed, 27 insertions(+)
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 0fcaf34d62..3fd26d5212 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -15,6 +15,9 @@ DESCRIPTION
-----------
Shows the commit logs.
+:git-log: 1
+include::rev-list-description.txt[]
+
The command takes options applicable to the linkgit:git-rev-list[1]
command to control what is shown and how, and options applicable to
the linkgit:git-diff[1] command to control how the changes
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index b06e11ae56..5da66232dc 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -14,6 +14,7 @@ SYNOPSIS
DESCRIPTION
-----------
+:git-rev-list: 1
include::rev-list-description.txt[]
'rev-list' is a very essential Git command, since it
diff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.txt
index 14d78b91aa..a9efa7fa27 100644
--- a/Documentation/rev-list-description.txt
+++ b/Documentation/rev-list-description.txt
@@ -12,9 +12,16 @@ result.
Thus, the following command:
+ifdef::git-rev-list[]
-----------------------------------------------------------------------
$ git rev-list foo bar ^baz
-----------------------------------------------------------------------
+endif::git-rev-list[]
+ifdef::git-log[]
+-----------------------------------------------------------------------
+$ git log foo bar ^baz
+-----------------------------------------------------------------------
+endif::git-log[]
means "list all the commits which are reachable from 'foo' or 'bar', but
not from 'baz'".
@@ -23,16 +30,32 @@ A special notation "'<commit1>'..'<commit2>'" can be used as a
short-hand for "^'<commit1>' '<commit2>'". For example, either of
the following may be used interchangeably:
+ifdef::git-rev-list[]
-----------------------------------------------------------------------
$ git rev-list origin..HEAD
$ git rev-list HEAD ^origin
-----------------------------------------------------------------------
+endif::git-rev-list[]
+ifdef::git-log[]
+-----------------------------------------------------------------------
+$ git log origin..HEAD
+$ git log HEAD ^origin
+-----------------------------------------------------------------------
+endif::git-log[]
Another special notation is "'<commit1>'...'<commit2>'" which is useful
for merges. The resulting set of commits is the symmetric difference
between the two operands. The following two commands are equivalent:
+ifdef::git-rev-list[]
-----------------------------------------------------------------------
$ git rev-list A B --not $(git merge-base --all A B)
$ git rev-list A...B
-----------------------------------------------------------------------
+endif::git-rev-list[]
+ifdef::git-log[]
+-----------------------------------------------------------------------
+$ git log A B --not $(git merge-base --all A B)
+$ git log A...B
+-----------------------------------------------------------------------
+endif::git-log[]
--
gitgitgadget
^ permalink raw reply related [flat|nested] 23+ messages in thread