diff --git a/.mailmap b/.mailmap
index a583a1ea9..1f74db3df 100644
--- a/.mailmap
+++ b/.mailmap
@@ -1,2 +1,7 @@
+# gitmailmap(5)
+# we use this to map author/commiter name and email addresses post-hoc
+# without git history rewrites. it is read by git-log and other git
+# tools implicitly.
+
 Alyssa Ross <hi@alyssa.is>
 Aspen Smith <root@gws.fyi> <aspen@gws.fyi> <grfn@gws.fyi>