diff options
author | Ævar Arnfjörð Bjarmason <avarab@gmail.com> | 2021-01-12 20:17:45 (GMT) |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2021-01-12 22:04:39 (GMT) |
commit | 42957af0273a338de232a6a0071a3ddcf92f9fee (patch) | |
tree | 2ddfedb8a1277deb8af3c3cc36ce0ca44e794a19 /Documentation/gitmailmap.txt | |
parent | 72c4083ddf91b489b7b7b812df67ee8842177d98 (diff) | |
download | git-42957af0273a338de232a6a0071a3ddcf92f9fee.zip git-42957af0273a338de232a6a0071a3ddcf92f9fee.tar.gz git-42957af0273a338de232a6a0071a3ddcf92f9fee.tar.bz2 |
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>
Diffstat (limited to 'Documentation/gitmailmap.txt')
-rw-r--r-- | Documentation/gitmailmap.txt | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/Documentation/gitmailmap.txt b/Documentation/gitmailmap.txt new file mode 100644 index 0000000..8b07f9c --- /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 <commit@email.xx> +-- + +The more complex forms are: +-- + <proper@email.xx> <commit@email.xx> +-- +which allows mailmap to replace only the email part of a commit, and: +-- + Proper Name <proper@email.xx> <commit@email.xx> +-- +which allows mailmap to replace both the name and the email of a +commit matching the specified commit email address, and: +-- + Proper Name <proper@email.xx> Commit Name <commit@email.xx> +-- +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@example.com> +Joe R. Developer <joe@example.com> +Jane Doe <jane@example.com> +Jane Doe <jane@laptop.(none)> +Jane D. <jane@desktop.(none)> +------------ + +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 <jane@desktop.(none)> +Joe R. Developer <joe@example.com> +------------ + +Note how there is no need for an entry for `<jane@laptop.(none)>`, because the +real name of that author is already correct. + +Example 2: Your repository contains commits from the following +authors: + +------------ +nick1 <bugs@company.xx> +nick2 <bugs@company.xx> +nick2 <nick2@company.xx> +santa <me@company.xx> +claus <me@company.xx> +CTO <cto@coompany.xx> +------------ + +Then you might want a `.mailmap` file that looks like: +------------ +<cto@company.xx> <cto@coompany.xx> +Some Dude <some@dude.xx> nick1 <bugs@company.xx> +Other Author <other@author.xx> nick2 <bugs@company.xx> +Other Author <other@author.xx> <nick2@company.xx> +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 |