Skip to content

doc: include git rev-list description in git log doc #590

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 6 commits into from
Closed

doc: include git rev-list description in git log doc #590

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
59027b0
git-log.txt: add links to 'rev-list' and 'diff' docs
phil-blain Mar 27, 2020
3c57369
revisions.txt: describe 'rev1 rev2 ...' meaning for ranges
phil-blain Jul 8, 2020
b8ee4a7
git-rev-list.txt: fix Asciidoc syntax
phil-blain Jul 3, 2020
cf934dd
git-rev-list.txt: tweak wording in set operations
phil-blain Jul 8, 2020
f61bbb5
git-rev-list.txt: move description to separate file
phil-blain Jul 3, 2020
d04b6c6
git-log.txt: include rev-list-description.txt
phil-blain Jul 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions Documentation/git-log.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,12 @@ DESCRIPTION
-----------
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Philippe Blain wrote (reply to this):

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...

Shows the commit logs.

The command takes options applicable to the `git rev-list`
: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 `git diff-*` commands to control how the changes
the linkgit:git-diff[1] command to control how the changes
each commit introduces are shown.


Expand Down
40 changes: 2 additions & 38 deletions Documentation/git-rev-list.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,44 +14,8 @@ 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
-----------------------------------------------------------------------
:git-rev-list: 1
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
Expand Down
61 changes: 61 additions & 0 deletions Documentation/rev-list-description.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
List commits that are reachable by following the `parent` links from the
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Philippe Blain wrote (reply to this):


> 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.

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:

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'".

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[]
3 changes: 3 additions & 0 deletions Documentation/revisions.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down