Merge branch 'ab/mailmap'
Clean-up docs, codepaths and tests around mailmap. * ab/mailmap: (22 commits) shortlog: remove unused(?) "repo-abbrev" feature mailmap doc + tests: document and test for case-insensitivity mailmap tests: add tests for empty "<>" syntax mailmap tests: add tests for whitespace syntax mailmap tests: add a test for comment syntax mailmap doc + tests: add better examples & test them tests: refactor a few tests to use "test_commit --append" test-lib functions: add an --append option to test_commit test-lib functions: add --author support to test_commit test-lib functions: document arguments to test_commit test-lib functions: expand "test_commit" comment template mailmap: test for silent exiting on missing file/blob mailmap tests: get rid of overly complex blame fuzzing mailmap tests: add a test for "not a blob" error mailmap tests: remove redundant entry in test mailmap tests: improve --stdin tests mailmap tests: modernize syntax & test idioms mailmap tests: use our preferred whitespace syntax mailmap doc: start by mentioning the comment syntax check-mailmap doc: note config options ...
This commit is contained in:
Junio C Hamano
@ -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
|
||||
|
||||
@ -226,7 +226,7 @@ commit commentary), a blame viewer will not care.
|
||||
MAPPING AUTHORS
|
||||
---------------
|
||||
|
||||
include::mailmap.txt[]
|
||||
See linkgit:gitmailmap[5].
|
||||
|
||||
|
||||
SEE ALSO
|
||||
|
||||
@ -36,10 +36,17 @@ name is provided or known to the 'mailmap', ``Name $$<user@host>$$'' is
|
||||
printed; otherwise only ``$$<user@host>$$'' is printed.
|
||||
|
||||
|
||||
CONFIGURATION
|
||||
-------------
|
||||
|
||||
See `mailmap.file` and `mailmap.blob` in linkgit:git-config[1] for how
|
||||
to specify a custom `.mailmap` target file or object.
|
||||
|
||||
|
||||
MAPPING AUTHORS
|
||||
---------------
|
||||
|
||||
include::mailmap.txt[]
|
||||
See linkgit:gitmailmap[5].
|
||||
|
||||
|
||||
GIT
|
||||
|
||||
@ -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
|
||||
---
|
||||
|
||||
123
Documentation/gitmailmap.txt
Normal file
123
Documentation/gitmailmap.txt
Normal file
@ -0,0 +1,123 @@
|
||||
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 (see linkgit:git-config[1]), it
|
||||
is used to map author and committer names and email addresses to
|
||||
canonical real names and email addresses.
|
||||
|
||||
|
||||
SYNTAX
|
||||
------
|
||||
|
||||
The '#' character begins a comment to the end of line, blank lines
|
||||
are ignored.
|
||||
|
||||
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.
|
||||
|
||||
Both E-Mails and names are matched case-insensitively. For example
|
||||
this would also match the 'Commit Name <commit@email.xx>' above:
|
||||
--
|
||||
Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX>
|
||||
--
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
|
||||
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 `.mailmap` file to
|
||||
correct the names would look like:
|
||||
|
||||
------------
|
||||
Joe R. Developer <joe@example.com>
|
||||
Jane Doe <jane@example.com>
|
||||
Jane Doe <jane@desktop.(none)>
|
||||
------------
|
||||
|
||||
Note that there's no need to map the name for 'jane@laptop.(none)' to
|
||||
only correct the names. However, leaving the obviously broken
|
||||
`<jane@laptop.(none)>' and '<jane@desktop.(none)>' E-Mails as-is is
|
||||
usually not what you want. A `.mailmap` file which also corrects those
|
||||
is:
|
||||
|
||||
------------
|
||||
Joe R. Developer <joe@example.com>
|
||||
Jane Doe <jane@example.com> <jane@laptop.(none)>
|
||||
Jane Doe <jane@example.com> <jane@desktop.(none)>
|
||||
------------
|
||||
|
||||
Finally, let's say that Joe and Jane shared an E-Mail address, but not
|
||||
a name, e.g. by having these two commits in the history generated by a
|
||||
bug reporting system. I.e. names appearing in history as:
|
||||
|
||||
------------
|
||||
Joe <bugs@example.com>
|
||||
Jane <bugs@example.com>
|
||||
------------
|
||||
|
||||
A full `.mailmap` file which also handles those cases (an addition of
|
||||
two lines to the above example) would be:
|
||||
|
||||
------------
|
||||
Joe R. Developer <joe@example.com>
|
||||
Jane Doe <jane@example.com> <jane@laptop.(none)>
|
||||
Jane Doe <jane@example.com> <jane@desktop.(none)>
|
||||
Joe R. Developer <joe@example.com> Joe <bugs@example.com>
|
||||
Jane Doe <jane@example.com> Jane <bugs@example.com>
|
||||
------------
|
||||
|
||||
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
linkgit:git-check-mailmap[1]
|
||||
|
||||
|
||||
GIT
|
||||
---
|
||||
Part of the linkgit:git[1] suite
|
||||
@ -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 <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.
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user