diff mbox series

[01/22] mailmap doc: create a new "gitmailmap(5)" man page

Message ID 20210112201806.13284-2-avarab@gmail.com (mailing list archive)
State New
Headers show
Series [01/22] mailmap doc: create a new "gitmailmap(5)" man page | expand

Commit Message

Ævar Arnfjörð Bjarmason Jan. 12, 2021, 8:17 p.m. UTC
Create a gitmailmap(5) page similar to how .gitmodules and .gitignore
have their own pages at gitmodules(5) and gitignore(5). Now instead of
"check-mailmap", "blame" and "shortlog" documentation including the
description of the format we link to one canonical place.

This makes things easier for readers, since in our manpage or
web-based[1] output it's not clear that the "MAPPING AUTHORS" sections
aren't subtly different, as opposed to just included.

1. https://git-scm.com/docs/git-check-mailmap

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/Makefile                        |  1 +
 Documentation/git-blame.txt                   |  2 +-
 Documentation/git-check-mailmap.txt           |  2 +-
 Documentation/git-shortlog.txt                |  6 +---
 Documentation/{mailmap.txt => gitmailmap.txt} | 33 +++++++++++++++++++
 command-list.txt                              |  1 +
 6 files changed, 38 insertions(+), 7 deletions(-)
 rename Documentation/{mailmap.txt => gitmailmap.txt} (88%)

Comments

Philippe Blain Jan. 14, 2021, 5:41 p.m. UTC | #1
Hi Ævar,

Le 2021-01-12 à 15:17, Ævar Arnfjörð Bjarmason a écrit :
> Create a gitmailmap(5) page similar to how .gitmodules and .gitignore
> have their own pages at gitmodules(5) and gitignore(5). Now instead of
> "check-mailmap", "blame" and "shortlog" documentation including the
> description of the format we link to one canonical place.
> 
> This makes things easier for readers, since in our manpage or
> web-based[1] output it's not clear that the "MAPPING AUTHORS" sections
> aren't subtly different, as opposed to just included.
> 
> 1. https://git-scm.com/docs/git-check-mailmap

I think that's a good idea.

> 
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
>   Documentation/Makefile                        |  1 +
>   Documentation/git-blame.txt                   |  2 +-
>   Documentation/git-check-mailmap.txt           |  2 +-
>   Documentation/git-shortlog.txt                |  6 +---
>   Documentation/{mailmap.txt => gitmailmap.txt} | 33 +++++++++++++++++++
>   command-list.txt                              |  1 +

Nice to see that the comment I added in Documentation/Makefile
about command-list.txt served its purpose :)

>   6 files changed, 38 insertions(+), 7 deletions(-)
>   rename Documentation/{mailmap.txt => gitmailmap.txt} (88%)
> 

-- 8< --

> diff --git a/Documentation/mailmap.txt b/Documentation/gitmailmap.txt
> similarity index 88%
> rename from Documentation/mailmap.txt
> rename to Documentation/gitmailmap.txt
> index 4a8c276529..8b07f9c5d7 100644
> --- a/Documentation/mailmap.txt
> +++ b/Documentation/gitmailmap.txt
> @@ -1,9 +1,28 @@
> +gitmailmap(5)
> +=============
> +
> +NAME
> +----
> +gitmailmap - Map author/committer names and/or E-Mail addresses
> +
> +SYNOPSIS
> +--------
> +$GIT_WORK_DIR/.mailmap

This should be GIT_WORK_TREE, gitmodules(5) is wrong as GIT_WORK_DIR
does not exists (my series at [1] fixes this).

Also, if you feel like this new guide should be featured in the "Guides" column
at git-scm.com/docs, I encourage you to submit a PR to the website. Though
I think for this specific guide, simply having it listed in git(1), linked from the
"All guides..." link at the bottom of that column, is sufficient.

Cheers,

Philippe.

[1] https://lore.kernel.org/git/pull.942.v2.git.git.1609695736001.gitgitgadget@gmail.com/
Junio C Hamano Jan. 14, 2021, 7:58 p.m. UTC | #2
Philippe Blain <levraiphilippeblain@gmail.com> writes:

>> +SYNOPSIS
>> +--------
>> +$GIT_WORK_DIR/.mailmap
>
> This should be GIT_WORK_TREE, gitmodules(5) is wrong as GIT_WORK_DIR
> does not exists (my series at [1] fixes this).

Well spotted.

Can you make the suggestion into a follow-up patch to the
series to be applied on top?

Thanks.
Philippe Blain Jan. 15, 2021, 2:38 a.m. UTC | #3
Hi Junio

Le 2021-01-14 à 14:58, Junio C Hamano a écrit :
> Philippe Blain <levraiphilippeblain@gmail.com> writes:
> 
>>> +SYNOPSIS
>>> +--------
>>> +$GIT_WORK_DIR/.mailmap
>>
>> This should be GIT_WORK_TREE, gitmodules(5) is wrong as GIT_WORK_DIR
>> does not exists (my series at [1] fixes this).
> 
> Well spotted.
> 
> Can you make the suggestion into a follow-up patch to the
> series to be applied on top?
> 

I just sent [1] as a fixup! commit (is that what you meant?)
I was not sure...) I feel it is cleaner for that commit to use
the correct variable name from the start, hence the fixup.

Philippe.

[1] https://lore.kernel.org/git/87zh1b51xk.fsf@evledraar.gmail.com/T/#m9e8e8f5458db71153c2363acf4bff959df7d0f4c
Junio C Hamano Jan. 15, 2021, 3:18 a.m. UTC | #4
Philippe Blain <levraiphilippeblain@gmail.com> writes:

> I was not sure...) I feel it is cleaner for that commit to use
> the correct variable name from the start, hence the fixup.

The topic is already in 'next', and that is why I asked follow-up
patches on top from people.  Otherwise I wouldn't have asked and
instead just squashed these fixes in while the topic was in 'seen'.

Thanks.
Philippe Blain Jan. 15, 2021, 3:36 a.m. UTC | #5
Le 2021-01-14 à 22:18, Junio C Hamano a écrit :
> Philippe Blain <levraiphilippeblain@gmail.com> writes:
> 
>> I was not sure...) I feel it is cleaner for that commit to use
>> the correct variable name from the start, hence the fixup.
> 
> The topic is already in 'next', and that is why I asked follow-up
> patches on top from people.  Otherwise I wouldn't have asked and
> instead just squashed these fixes in while the topic was in 'seen'.

OK, thanks for clarifying. I did not check the status of the series,
probably because I saw it was from just 2 days ago so I did not think it
would already be in next. I just sent a v2 with a proper commit message [2].

I'm still not sure I have should have sent it as a reply to the commit it's
fixing (as I did), or to the last commit of the series, or to the cover letter,
or as a new thread to the list... what's the etiquette around this ?
(I'm still new to the email workflow, especially around multi-author series...)

Philippe.

[2] https://lore.kernel.org/git/20210115032826.51369-1-levraiphilippeblain@gmail.com/
Junio C Hamano Jan. 15, 2021, 5:53 a.m. UTC | #6
Philippe Blain <levraiphilippeblain@gmail.com> writes:

> I'm still not sure I have should have sent it as a reply to the commit it's
> fixing (as I did), or to the last commit of the series, or to the cover letter,
> or as a new thread to the list... what's the etiquette around this ?

I can deal with any of the above, but with the goal of keeping the
list archive most useful for later readers, I would imagine that it
would be best if such a follow-up fix were made against the specific
step (if there is such a single step) that introduced an issue (in
other words, where you would have squashed your fix into, if it were
under your control to redo the series).  If there is no such single
step and the fix applies to the whole series in general, a response
to its cover letter would also do, I would think.

Thanks.
diff mbox series

Patch

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b980407059..81d1bf7a04 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -21,6 +21,7 @@  MAN1_TXT += gitweb.txt
 MAN5_TXT += gitattributes.txt
 MAN5_TXT += githooks.txt
 MAN5_TXT += gitignore.txt
+MAN5_TXT += gitmailmap.txt
 MAN5_TXT += gitmodules.txt
 MAN5_TXT += gitrepository-layout.txt
 MAN5_TXT += gitweb.conf.txt
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 34b496d485..3bf5d5d8b4 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -226,7 +226,7 @@  commit commentary), a blame viewer will not care.
 MAPPING AUTHORS
 ---------------
 
-include::mailmap.txt[]
+See linkgit:gitmailmap[5].
 
 
 SEE ALSO
diff --git a/Documentation/git-check-mailmap.txt b/Documentation/git-check-mailmap.txt
index aa2055dbeb..45a5cfafd8 100644
--- a/Documentation/git-check-mailmap.txt
+++ b/Documentation/git-check-mailmap.txt
@@ -39,7 +39,7 @@  printed; otherwise only ``$$<user@host>$$'' is printed.
 MAPPING AUTHORS
 ---------------
 
-include::mailmap.txt[]
+See linkgit:gitmailmap[5].
 
 
 GIT
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index fd93cd41e9..c16cc3b608 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -111,11 +111,7 @@  include::rev-list-options.txt[]
 MAPPING AUTHORS
 ---------------
 
-The `.mailmap` feature is used to coalesce together commits by the same
-person in the shortlog, where their name and/or email address was
-spelled differently.
-
-include::mailmap.txt[]
+See linkgit:gitmailmap[5].
 
 GIT
 ---
diff --git a/Documentation/mailmap.txt b/Documentation/gitmailmap.txt
similarity index 88%
rename from Documentation/mailmap.txt
rename to Documentation/gitmailmap.txt
index 4a8c276529..8b07f9c5d7 100644
--- a/Documentation/mailmap.txt
+++ b/Documentation/gitmailmap.txt
@@ -1,9 +1,28 @@ 
+gitmailmap(5)
+=============
+
+NAME
+----
+gitmailmap - Map author/committer names and/or E-Mail addresses
+
+SYNOPSIS
+--------
+$GIT_WORK_DIR/.mailmap
+
+
+DESCRIPTION
+-----------
+
 If the file `.mailmap` exists at the toplevel of the repository, or at
 the location pointed to by the mailmap.file or mailmap.blob
 configuration options, it
 is used to map author and committer names and email addresses to
 canonical real names and email addresses.
 
+
+SYNTAX
+------
+
 In the simple form, each line in the file consists of the canonical
 real name of an author, whitespace, and an email address used in the
 commit (enclosed by '<' and '>') to map to the name. For example:
@@ -27,6 +46,10 @@  commit matching the specified commit email address, and:
 which allows mailmap to replace both the name and the email of a
 commit matching both the specified commit name and email address.
 
+
+EXAMPLES
+--------
+
 Example 1: Your history contains commits by two authors, Jane
 and Joe, whose names appear in the repository under several forms:
 
@@ -73,3 +96,13 @@  Santa Claus <santa.claus@northpole.xx> <me@company.xx>
 
 Use hash '#' for comments that are either on their own line, or after
 the email address.
+
+
+SEE ALSO
+--------
+linkgit:git-check-mailmap[1]
+
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/command-list.txt b/command-list.txt
index 9379b02e5e..a289f09ed6 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -204,6 +204,7 @@  gitfaq                                  guide
 gitglossary                             guide
 githooks                                guide
 gitignore                               guide
+gitmailmap                              guide
 gitmodules                              guide
 gitnamespaces                           guide
 gitremote-helpers                       guide