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

From: Philippe Blain <levraiphilippeblain@gmail.com>
Date: Jan 14, 2021, 17:41 UTC
Message-ID: <a71860ee-6810-8766-b9c7-4c03ea7e6e01@gmail.com>
In-Reply-To: <20210112201806.13284-2-avarab@gmail.com>

Hi Ævar,

Le 2021-01-12 à 15:17, Ævar Arnfjörð Bjarmason a écrit :

Show 10 quoted lines

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

Show 9 quoted lines

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

Show 18 quoted lines

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