Table of Contents

Updating the .mailmap file

The .mailmap file allows Git to handle user aliases.

It is useful to maintain a clean and consistent list of authors, for example if users changed e-mail addresses or used different names when checking in their commits.

Identifying duplicate authors in Git history

This section provides commands to identify duplicates that require an entry in the .mailmap file.

This section is for documentation purposes only.

Since 2.25.8, these checks are executed as part of the update-credits.sh script, which will output a list of duplicate entries to be added. Skip to the Updating .mailmap section below.

If there is no output, then there's nothing to do ! :-)

Multiple e-mail addresses

The following command will print a list of Author names having more than one e-mail address not already aliased in mailmap. 

git log --format='%aN <%aE>' | sort -u | awk -F'<' '{print $1}' | uniq -c | grep -v '^ *1 '| cut -c9-

Multiple names

The following command will print a list of Author e-mail addresses linked to more than one name, and not already aliased in mailmap. 

git log --format='%aE %aN' | sort -u | awk '{print $1}' | uniq -c | grep -v '^ *1 ' | cut -c9-

Updating .mailmap

Add aliases to the .mailmap file for each entry in the lists generated by the above commands. The following command will identify what needs to be added (replace XXX by the entry) 

git log --author="XXX" --format="%aN <%aE>" | sort -u

See Reference section below for details about .mailmap file syntax.

Example

The example below was generated on the MantisBT repository, after removing Victor's aliases from the .mailmap file.

  1. Identify duplicates 
    $ git log --format='%aN <%aE>' | sort -u | awk -F'<' '{print $1}' | uniq -c | grep -v '^ *1 '| cut -c9-
Victor Boctor 

$ git log --author="Victor Boctor" --format="%aN <%aE>" |sort -u
Victor Boctor <vboctor@gmail.com>
Victor Boctor <vboctor@localhost.localdomain>
Victor Boctor <vboctor@new-host-3.home>
Victor Boctor <victor@mantishub.com>
Victor Boctor <victor@mantishub.net>
  2. Edit .mailmap file to add aliases 
    Victor Boctor <vboctor@gmail.com> root <root@localhost.localdomain>
Victor Boctor <vboctor@gmail.com> <vboctor@localhost.localdomain>
Victor Boctor <vboctor@gmail.com> <vboctor@new-host-3.home>
Victor Boctor <vboctor@gmail.com> <victor@mantishub.com>
Victor Boctor <vboctor@gmail.com> <victor@mantishub.net>
  3. Check again: only a single entry is displayed now 
    $ git log --author="Victor Boctor" --format="%aN <%aE>" |sort -u
Victor Boctor <vboctor@gmail.com>

References