From 42957af0273a338de232a6a0071a3ddcf92f9fee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Tue, 12 Jan 2021 21:17:45 +0100 Subject: mailmap doc: create a new "gitmailmap(5)" man page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Junio C Hamano --- Documentation/Makefile | 1 + Documentation/git-blame.txt | 2 +- Documentation/git-check-mailmap.txt | 2 +- Documentation/git-shortlog.txt | 6 +- Documentation/gitmailmap.txt | 108 ++++++++++++++++++++++++++++++++++++ Documentation/mailmap.txt | 75 ------------------------- command-list.txt | 1 + 7 files changed, 113 insertions(+), 82 deletions(-) create mode 100644 Documentation/gitmailmap.txt delete mode 100644 Documentation/mailmap.txt 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 ``$$$$'' 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/gitmailmap.txt b/Documentation/gitmailmap.txt new file mode 100644 index 0000000000..8b07f9c5d7 --- /dev/null +++ b/Documentation/gitmailmap.txt @@ -0,0 +1,108 @@ +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: +-- + Proper Name +-- + +The more complex forms are: +-- + +-- +which allows mailmap to replace only the email part of a commit, and: +-- + Proper Name +-- +which allows mailmap to replace both the name and the email of a +commit matching the specified commit email address, and: +-- + Proper Name Commit Name +-- +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: + +------------ +Joe Developer +Joe R. Developer +Jane Doe +Jane Doe +Jane D. +------------ + +Now suppose that Joe wants his middle name initial used, and Jane +prefers her family name fully spelled out. A proper `.mailmap` file +would look like: + +------------ +Jane Doe +Joe R. Developer +------------ + +Note how there is no need for an entry for ``, because the +real name of that author is already correct. + +Example 2: Your repository contains commits from the following +authors: + +------------ +nick1 +nick2 +nick2 +santa +claus +CTO +------------ + +Then you might want a `.mailmap` file that looks like: +------------ + +Some Dude nick1 +Other Author nick2 +Other Author +Santa Claus +------------ + +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/Documentation/mailmap.txt b/Documentation/mailmap.txt deleted file mode 100644 index 4a8c276529..0000000000 --- a/Documentation/mailmap.txt +++ /dev/null @@ -1,75 +0,0 @@ -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. - -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: --- - Proper Name --- - -The more complex forms are: --- - --- -which allows mailmap to replace only the email part of a commit, and: --- - Proper Name --- -which allows mailmap to replace both the name and the email of a -commit matching the specified commit email address, and: --- - Proper Name Commit Name --- -which allows mailmap to replace both the name and the email of a -commit matching both the specified commit name and email address. - -Example 1: Your history contains commits by two authors, Jane -and Joe, whose names appear in the repository under several forms: - ------------- -Joe Developer -Joe R. Developer -Jane Doe -Jane Doe -Jane D. ------------- - -Now suppose that Joe wants his middle name initial used, and Jane -prefers her family name fully spelled out. A proper `.mailmap` file -would look like: - ------------- -Jane Doe -Joe R. Developer ------------- - -Note how there is no need for an entry for ``, because the -real name of that author is already correct. - -Example 2: Your repository contains commits from the following -authors: - ------------- -nick1 -nick2 -nick2 -santa -claus -CTO ------------- - -Then you might want a `.mailmap` file that looks like: ------------- - -Some Dude nick1 -Other Author nick2 -Other Author -Santa Claus ------------- - -Use hash '#' for comments that are either on their own line, or after -the email address. 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 -- cgit v1.2.3