mailmap

.mailmap

Git 저장소에서 여러 기여자가 서로 다른 이름이나 이메일로 커밋할 때, 동일 인물의 기여 내역이 분산되어 나타나는 경우가 있습니다. 예를 들어, 한 사람이 실수로 이름 철자를 바꾸거나 이메일 주소를 다르게 입력하는 경우가 있죠. 이러한 문제를 해결하기 위해 .mailmap 파일을 사용하면, 여러 이름과 이메일을 통합하여 하나의 정규화된 정보로 표시할 수 있습니다.

---

역할

• 기여자 통합 Git 로그, git shortlog, git blame 등에서 동일 인물의 커밋을 하나로 묶어 보여주므로, 통계와 기여도 집계가 명확해집니다.

• 일관된 기여자 정보 제공 다양한 이름/이메일 조합을 하나의 표준 정보로 매핑하여, 프로젝트 히스토리의 일관성을 유지합니다.

• 협업 시 혼란 최소화 기여자 목록이 중복되어 나타나는 것을 방지하고, 각 기여자의 실제 기여 내역을 명확하게 파악할 수 있습니다.

---

기본 문법

.mailmap 파일은 저장소 루트에 위치하며, 각 줄에 하나의 매핑 규칙을 기록합니다. 기본 문법은 아래와 같습니다.

• 표준 이름과 이메일: 정규화된 기여자 정보를 맨 앞에 작성합니다.

• 별칭(또는 이전 이름)과 이메일: 정규화된 정보 뒤에 별칭이나 잘못 기입된 정보를 작성하여, 해당 정보를 정규화된 정보로 치환합니다.

• 형식 예시:

# 표준 이름과 이메일을 기준으로 별칭 매핑
John Doe <[email protected]>  johnd <[email protected]>
Jane Smith <[email protected]>  J. Smith <[email protected]>

위 예제에서 "johnd" 또는 "[email protected]"로 기록된 커밋은 모두 "John Doe [email protected]"으로 정규화되어 표시됩니다.

---

활용하기

• 기여 내역 정리 팀원들이 다양한 이름으로 커밋한 경우, .mailmap을 통해 한 명의 기여자로 통합할 수 있습니다. 예를 들어, GitHub에서 기여 내역을 집계할 때 기여자가 여러 개의 다른 이메일로 나타난다면, 이를 하나로 합쳐 정확한 기여 통계를 볼 수 있습니다.

• 명령어 활용 .mailmap 파일은 별도의 설정 없이 Git 명령어에 자동으로 적용됩니다. git shortlog -sne 명령어를 실행하면, .mailmap에 정의된 매핑 규칙에 따라 기여자 목록이 정리되어 출력됩니다.

• 관리 팁 팀 내부에서 이름과 이메일 표기가 일관되지 않을 경우, 미리 .mailmap 파일을 만들어 두고 커밋 규칙에 포함시키면 좋습니다. 예를 들어, 초기 프로젝트 세팅 시 협업 가이드라인에 “모든 기여자는 .mailmap에 본인 정보를 등록”하는 절차를 추가할 수 있습니다.