mailmap doc: create a new "gitmailmap(5)" man page

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b9804070594d9cd33dfc1e30cdd925c6e83a2187..81d1bf7a049b31b553b215aa7c58d92006bb544b 100644 (file)
--- 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 34b496d4858134fb5c5e91bbd1537cd3ae076ccf..3bf5d5d8b4abe78a1be0f811640e516d6868b346 100644 (file)
--- 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 aa2055dbebcd4237e7557db7926700c933f8ac94..45a5cfafd80a7a0964ace86afbef3bc436ef85ba 100644 (file)
--- 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 fd93cd41e90c7d7b6c5b9dcbc904681a0b247254..c16cc3b6089c6333de23117e5acaff36fa30b76f 100644 (file)
--- 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 4a8c276529a574355185adf3c77dede6fbd94267..8b07f9c5d73c5bbc2c93e5f931681823afa95e1b 100644 (file)
--- 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 9379b02e5e90e8b91071550d3ee6da8a11b5a123..a289f09ed6fbf9a117468ae69c7ee2e8ab48f0a8 100644 (file)
--- 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