mailmap Git Command Guide

Git mailmap allows mapping multiple author names and email addresses to canonical names and email addresses. This ensures consistent attribution across different email aliases, name formats, and email addresses used by the same person in Git commits.

git check-mailmap Syntax:

git check-mailmap [--stdin] [--mailmap-file=<file>] [--] [<contact>...]

Mailmap File Format:

Basic email normalization:

Proper Name <proper@email.com>

Name and email mapping:

Proper Name <proper@email.com> <commit@email.com>
Nick Name <nick@email.com> <original@email.com>

Multiple aliases to one person:

Canonical Name <canonical@email.com> <alias1@email.com>
Canonical Name <canonical@email.com> <alias2@email.com>
Canonical Name <canonical@email.com> Name <alias3@email.com>

Email only normalization:

<canonical@email.com> <alias@email.com>

Mailmap Configuration:

Project mailmap file:

# .mailmap file in repository root
Proper Name <proper@email.com> improper@email.com
Nick Name <nick@email.com> <original@email.com>
Canonical Name <canonical@email.com> <alias1@email.com>
Canonical Name <canonical@email.com> <alias2@email.com>

Global mailmap configuration:

# Set global mailmap file
git config --global mailmap.file ~/.mailmap

# Use multiple mailmap files
git config --global mailmap.file 'file:///home/user/.mailmap'
git config mailmap.file '.mailmap'

Automatic mailmap usage:

# Show log with mailmap mapping
git log --use-mailmap

# Shortlog with consistent names
git shortlog --group=author --use-mailmap

# Blame with proper names
git blame --use-mailmap HEAD

Mailmap File Options:

Option	Description
--stdin	Read contacts from standard input
--mailmap-file=<file>	Use specified mailmap file

Parameters:

Parameter	Description
<contact>...	Name and email addresses to normalize

Identity Mapping Examples:

Single name normalization:

# Input: Alias Name <alias@email.com>
# Mailmap: Canonical Name <canonical@email.com> <alias@email.com>
# Output: Canonical Name <canonical@email.com>

Email-only correction:

# Input: Name <old@email.com>
# Mailmap: <new@email.com> <old@email.com>
# Output: Name <new@email.com>

Multiple identities one person:

# Input: Various formats from different commits
# Mailmap entries:
# Canonical Name <canonical@email.com> <work@email.com>
# Canonical Name <canonical@email.com> <personal@email.com>
# Canonical Name <canonical@email.com> Old Name <old@email.com>
# Output: All resolve to Canonical Name <canonical@email.com>

Basic Usage Examples:

Check single contact:

# Check if email is mapped
git check-mailmap "jsmith@example.com"

# Check name and email
git check-mailmap "John Smith <jsmith@example.com>"

Process multiple contacts:

# Check multiple entries
git check-mailmap "Developer A <a@company.com>" "Dev B <b@company2.com>"

# Read from stdin
echo -e "name1@email.com\nname2@email.com" | git check-mailmap --stdin

Use custom mailmap file:

# Use different mailmap file
git check-mailmap --mailmap-file="/path/to/other.mailmap" user@example.com

# Combine with project mailmap
git check-mailmap --mailmap-file=".mailmap" john.doe@example.com

Advanced Mailmap Setup:

Repository collaboration scenarios:

Corporate environment:

# .mailmap for enterprise development
John Doe <john.doe@company.com> <john.doe@personal.com>
John Doe <john.doe@company.com> JohnnyD <johnny@old-company.com>
Jane Smith <jane.smith@company.com> <jane.smith@consulting.com>
Jane Smith <jane.smith@company.com> Jane <jane@vendor.com>

Open-source project:

# Contributors using different emails
Maintainer <maintainer@example.org> <maintainer@gmail.com>
Maintainer <maintainer@example.org> maint <maint@old-email.com>
Contributor <contributor@example.org> <contrib@personal.com>
Contributor <contributor@example.org> contrib <contrib@work.com>

Name standardization:

# Handle different name variations
# Input variations: John, Johnny, J. Doe, john doe
# All map to: John Doe
John Doe <john.doe@example.com> John <john@email.com>
John Doe <john.doe@example.com> Johnny <johnny@email.com>
John Doe <john.doe@example.com> J. Doe <j.doe@email.com>
John Doe <john.doe@example.com> john doe <john@email.com>

Integration with Git Features:

Log and shortlog consistency:

# View commit history with consistent names
git log --use-mailmap --format="%aN <%aE>"

# Generate contributor statistics
git shortlog --group=author --use-mailmap -n

# Show contributions by author
git shortlog --group=author --use-mailmap -sn

Blame with proper attribution:

# Show blame with canonical names
git blame --use-mailmap HEAD -- file.txt

# Track changes by person, not email
git blame --use-mailmap HEAD | grep "Canonical Name"

Reflog with consistent identity:

# View reflog with mapped identities
git reflog --use-mailmap | head -10

# Find operations by specific person
git reflog --grep="Canonical Name" --use-mailmap

Mailmap Validation and Debugging:

Verify mailmap configuration:

# Check mailmap file location
git config --list | grep mailmap

# Test mailmap mappings
git check-mailmap --mailmap-file=".mailmap" "testuser@example.com"

# Validate against commit history
git log --use-mailmap --all --format="%aN <%aE>" | sort | uniq -c | sort -nr

Find unmapped contributors:

# Identify contributors without mailmap entries
git log --pretty="%aN <%aE>" | sort | uniq > all-contributors.txt

# Check which ones are unmapped
while read -r contributor; do
    result=$(git check-mailmap "$contributor")
    if [ "$result" != "$contributor" ]; then
        echo "Mapped: $contributor -> $result"
    else
        echo "Unmapped: $contributor"
    fi
done < all-contributors.txt

Statistics and analysis:

# Count total contributors (before/after mailmap)
echo "Before mailmap:"
git log --pretty="%aN <%aE>" | sort | uniq | wc -l

echo "After mailmap:"
git log --pretty="%aN <%aE>" --use-mailmap | sort | uniq | wc -l

# Find duplicate names that should be the same person
git log --pretty="%aN" --use-mailmap | sort | uniq -d

Configuration Best Practices:

File naming and location:

# Repository-specific mailmap
.mailmap

# Global mailmap for all repositories
~/.git-mailmap

# Organization-wide mailmap
/path/to/company/.mailmap

Systematic name standardization:

# .mailmap example for consistent formatting

# Standardize to "First Last <email>"" format
John Smith <john.smith@example.com> <jsmith@example.com>
John Smith <john.smith@example.com> Smith, John <johnsmith@example.com>
John Smith <john.smith@example.com> jsmith <jsmith@example.com>

# Handle name variations
Sarah Johnson <sarah.johnson@example.com> Sarah <sjohnson@example.com>
Sarah Johnson <sarah.johnson@example.com> S. Johnson <sjohnson@example.com>

Email domain normalization:

# Map different email providers/servers for same person
Developer <developer@company.com> <dev@gmail.com>
Developer <developer@company.com> Developer <dev@company-mail.com>
Developer <developer@company.com> dev <dev@old-domain.com>

Troubleshooting Common Issues:

Mailmap not working:

# Check if mailmap file exists
ls -la .mailmap
cat .mailmap

# Verify mailmap syntax
git check-mailmap --mailmap-file=".mailmap" "test@example.com"

# Check git configuration
git config --list | grep mailmap

Incorrect mappings:

# Test specific mapping
git check-mailmap "Problem Case <problem@example.com>"

# Debug mapping logic
# Edit .mailmap and test incrementally
echo "Test Case <test@example.com>" >> .mailmap
git check-mailmap "Test Case <test@example.com>"

Case sensitivity issues:

# Email addresses are case-sensitive
# Names are case-sensitive in mailmap
# Check for exact matches
git check-mailmap "John Doe <john@example.com>"

Permissions and access:

# Mailmap file should be tracked
git ls-files | grep -i mailmap

# Make sure it's readable
ls -la .mailmap

Caution

Mailmap doesn’t change existing commits - it only affects how names/emails are displayed. Mailmap entries are case-sensitive. Keep mailmap file committed and shared with the team.

Real-World Usage Examples:

Corporate contributor normalization:

# Handle corporate identity changes
Former Name <current@company.com> Former <former@company.com>
Former Name <current@company.com> fname <fname@oldcompany.com>

# Map contractor identities
Employee <employee@company.com> Contractor <contractor@vendor.com>
Employee <employee@company.com> consultant <consultant@agency.com>

Open-source contribution mapping:

# Handle different contribution platforms
Contributor <contributor@example.org> contributor@github.com <github-id@users.noreply.github.com>
Contributor <contributor@example.org> contrib <contrib@sourceforge.net>
Contributor <contributor@example.org> Contributor <contrib@patchwork.kernel.org>

Automated mailmap maintenance:

#!/bin/bash
# Generate mailmap from git log analysis

echo "# Auto-generated mailmap based on contributor patterns" > .mailmap
echo "" >> .mailmap

# Find contributors and generate mappings
git log --pretty="%aN|%aE" | sort | uniq | \
while IFS='|' read -r name email; do
    if [[ $email == *"noreply"* ]] || [[ $email == *"users"* ]]; then
        # Likely GitHub/GitLab generated
        base_email=$(echo "$email" | sed 's/+.*@/@/;s/@users.noreply.//;s/@.*noreply.//')
        echo "$name <$base_email> <$email>" >> .mailmap
    fi
done

echo "Generated mailmap:"
cat .mailmap

Tip

Use mailmap for consistent contributor attribution. Create comprehensive mappings for all contributor variations. Keep mailmap file in repository root and committed.

How does mailmap relate to .authors or credits files?

Mailmap provides programmatic mapping for Git commands, while .authors files are human-readable. Mailmap affects git log/blame output automatically.

What’s the difference between mailmap and Git author configuration?

Mailmap maps existing commits’ author information; git config sets author for new commits. Mailmap is retrospective, config is prospective.

Can mailmap handle committed author information changes?

Yes, it can map old author names/emails to canonical ones. Use rename detection to find all variations used by a contributor.

How do I create mailmap entries from existing commits?

Analyze git log output to identify author variations: git log —pretty=“%aN <%aE>” | sort | uniq. Then create mappings for each variation.

What’s the performance impact of mailmap?

Negligible - mailmap lookup is fast unless using very large files. Load time is minimal compared to git log operations.

Can mailmap work with GitHub/GitLab profiles?

No direct integration, but can map GitHub-generated email addresses to canonical identities. Useful for contributor consistency across platforms.

How do I share mailmap across multiple repositories?

Keep mailmap file in each repository, or use global mailmap configuration. Shared organization repositories can benefit from team mailmap standards.

What’s the syntax for name-only mapping?

Name-only mapping: “Canonical Name canonical@email.com” without additional parameters maps the canonical name to itself for consistency.

Can mailmap handle international characters?

Yes, fully supports UTF-8 encoding. Mailmap files should be UTF-8 encoded for proper international name handling.

How do I validate mailmap correctness?

Use git check-mailmap to test mappings, and git log —use-mailmap to verify display changes. Review output for unexpected consolidations.

What’s the relationship between mailmap and Git aliases?

Mailmap maps contributor identities; Git aliases are shortcuts for commands. Different purposes - mailmap for contributor attribution consistency.

Can mailmap be used for commit message formatting?

No - mailmap only affects author/committer names and emails, not commit messages, subjects, or other commit metadata.

Applications of the mailmap command

1. Contributor Attribution: Ensure consistent author attribution across different email aliases and name variations
2. Project Analytics: Generate accurate statistics on contributions by consolidating multiple identities of same person
3. Code Review Integrity: Provide consistent author identification in code review tools and workflows
4. Compliance Reporting: Enable accurate contributor tracking for license compliance and security audits
5. Open-Source Project Management: Maintain proper credit attribution for contributions from various platforms and aliases
6. Corporate Collaboration: Standardize contributor identities across different company domains and naming conventions