[v2,1/4] git-log.txt: add links to 'rev-list' and 'diff' docs
diff mbox series

Message ID 59c48282a094e90b7f4635c4cbcc04b1914b4c0e.1593747509.git.gitgitgadget@gmail.com
State New
Headers show
Series
  • doc: include git rev-list description in git log doc
Related show

Commit Message

Junio C Hamano via GitGitGadget July 3, 2020, 3:38 a.m. UTC
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(-)

Comments

Junio C Hamano July 7, 2020, 12:55 a.m. UTC | #1
"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.
Philippe Blain July 7, 2020, 1:11 p.m. UTC | #2
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...

Patch
diff mbox series

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.