summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLibravatar Ævar Arnfjörð Bjarmason <avarab@gmail.com>2021-01-12 21:17:45 +0100
committerLibravatar Junio C Hamano <gitster@pobox.com>2021-01-12 14:04:39 -0800
commit42957af0273a338de232a6a0071a3ddcf92f9fee (patch)
tree2ddfedb8a1277deb8af3c3cc36ce0ca44e794a19
parentThe first batch in 2.31 cycle (diff)
downloadtgif-42957af0273a338de232a6a0071a3ddcf92f9fee.tar.xz
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>
-rw-r--r--Documentation/Makefile1
-rw-r--r--Documentation/git-blame.txt2
-rw-r--r--Documentation/git-check-mailmap.txt2
-rw-r--r--Documentation/git-shortlog.txt6
-rw-r--r--Documentation/gitmailmap.txt (renamed from Documentation/mailmap.txt)33
-rw-r--r--command-list.txt1
6 files changed, 38 insertions, 7 deletions
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
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