Why Is Your Git History So Messy?
Have you ever run the git shortlog -sn command to track contributions only to get a hilarious yet frustrating result? A colleague named “Nguyen Van A” appears four times. Sometimes as nguyenvana, other times as A Nguyen, [email protected], or worst of all, [email protected].
This situation is incredibly common in long-term projects. In one repo I managed, despite having only 12 members, the author list grew to 50 names. This usually happens when team members forget to configure git config or use personal machines for quick bug fixes. Consequently, statistical data becomes inaccurate, and traceability becomes a nightmare.
Many people immediately think of git filter-branch or BFG to fix the history. Don’t do that! I once wasted an entire afternoon after a wrong force push while rewriting history. There is a safer solution that doesn’t change commit hashes: .mailmap.
.mailmap – A Smart Filter for Git
Basically, .mailmap acts as a mapping layer. It doesn’t modify the original data in the Git database. Instead, when you run git log or git blame, Git checks this file to display names and emails according to the rules you define.
Think of it as a smart contact list. No matter if the caller uses a landline, a personal number, or a work number, the phone still displays a single name. Everything becomes organized without touching the old commit structure.
Detailed .mailmap Configuration Guide
1. Initialization
Simply create a plain text file named .mailmap in the root directory of your project:
touch .mailmap2. Common Syntax
The syntax of this file is very flexible. Here are the three scenarios I apply most often:
Merge multiple emails into one standard name:
Used when one person uses various emails but the display name is the same.
Proper Name <[email protected]> <[email protected]>
Proper Name <[email protected]> <[email protected]>Correct both wrong names and emails:
Map an exact old identifier pair to a new one.
Proper Name <[email protected]> Commit Name <[email protected]>Standardize only the name for a specific email:
Useful when the email is correct but the display name is a nickname or computer name.
Proper Name <[email protected]>3. Real-world Project Example
Suppose your colleague “Tran Van Tu” is cluttering the log with three different identifiers. I would write the .mailmap file as follows:
Tran Van Tu <[email protected]> <[email protected]>
Tran Van Tu <[email protected]> Tu Tran <[email protected]>
Tran Van Tu <[email protected]> tu.tran <[email protected]>Save the file and try running git shortlog -sn. You’ll see the magic: the three previously separate lines have merged into a single entry under the name “Tran Van Tu.”
Maximize the Power of .mailmap
The true power of .mailmap lies in the git blame command. When you need to find who was responsible for a line of code from three years ago, you’ll see their real name instead of an obscure, inactive email.
Since Git version 2.9.0, most commands automatically recognize this file if it’s in the root. However, to be sure or when using older tools, you can add the flag:
git log --use-mailmapMy personal experience is to commit this .mailmap file to the repo. That way, all team members benefit from a clean project history. Monthly contribution reports will save you at least 30-45 minutes of manual tallying.
A Few Tips to Avoid Errors
- Order: Git reads the file from top to bottom. The first matching rule takes priority.
- Precision: Git is case-sensitive regarding emails. You should copy emails directly from the log to avoid mistakes.
- Syntax: Always include a space between the name and the angle brackets
< >. Without this space, Git will ignore your file.
Conclusion
Cleaning up Git doesn’t always require “heavy-duty” techniques. With just a small text file, you can demonstrate professionalism and attention to detail in source code management. Try creating a .mailmap today; your colleagues will surely thank you for the organization!
