{"thread":{"id":"16868","subject":"[PATCH] git-shortlog.txt: improve documentation about .mailmap files","startedAt":"2008-12-26T11:18:03Z","lastAt":"2008-12-27T11:48:39Z","messageCount":3,"participants":["Adeodato Simó","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"98721","messageId":"1230290283-6268-1-git-send-email-dato@net.com.org.es","threadId":"16868","inReplyTo":null,"subject":"[PATCH] git-shortlog.txt: improve documentation about .mailmap files","fromName":"Adeodato Simó","fromEmail":"dato@net.com.org.es","sentAt":"2008-12-26T11:18:03Z","receivedAt":"2008-12-26T11:18:03Z","isPatch":true,"sender":{"key":"dato@net.com.org.es","avatar":"https://gravatar.com/avatar/952ec7d5d5663eb8baf631b5c37f9c58480a881920dd5f8a2d3a71f969b72b53?d=mp&s=160"},"body":"The previous .mailmap example made it seem like .mailmap files are only\nuseful for commits with a wrong address for an author, when they are about\nfixing the real name. Explained this better in the text, and replaced the\nexisting example with a new one that hopefully makes things clearer.\n---\n Documentation/git-shortlog.txt | 31 ++++++++++++++++++++++++-------\n 1 files changed, 24 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex 7ccf31c..69e10a4 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -48,15 +48,32 @@ OPTIONS\n FILES\n -----\n \n-If the file `.mailmap` exists, it will be used for mapping author\n-email addresses to a real author name. One mapping per line, first\n-the author name followed by the email address enclosed by\n-'<' and '>'. Use hash '#' for comments. Example:\n+If a file `.mailmap` exists in the toplevel directory of the repository,\n+it will be used for mapping author email addresses to a canonical real\n+name. This can be used to coalesce together commits by the same person\n+where their name was spelled differently (whether with the same email\n+address or not).\n+\n+The format of the file is one mapping per line, first the desired author\n+name followed by the email address enclosed by '<' and '>'. Use hash '#'\n+for comments. For example, if your history contains commits by these\n+committers:\n+\n+------------\n+Author: Joe Developer \n+Author: Joe R. Developer \n+Author: Jane Doe \n+Author: Jane Doe \n+Author: Jane D. \n+------------\n+\n+Then a proper `.mailmap` file would be:\n \n ------------\n-# Keep alphabetized\n-Adam Morrow \n-Eve Jones \n+# Note how we don't need an entry for , because the\n+# real name of that author is correct already, and coalesced directly.\n+Jane Doe \n+Joe R. Developer \n ------------\n \n Author\n-- \n1.6.1\n"},{"id":"98725","messageId":"1230292553-7613-1-git-send-email-dato@net.com.org.es","threadId":"16868","inReplyTo":"1230290283-6268-1-git-send-email-dato@net.com.org.es","subject":"[PATCH] git-shortlog.txt: improve documentation about .mailmap files","fromName":"Adeodato Simó","fromEmail":"dato@net.com.org.es","sentAt":"2008-12-26T11:55:53Z","receivedAt":"2008-12-26T11:55:53Z","isPatch":true,"sender":{"key":"dato@net.com.org.es","avatar":"https://gravatar.com/avatar/952ec7d5d5663eb8baf631b5c37f9c58480a881920dd5f8a2d3a71f969b72b53?d=mp&s=160"},"body":"The previous .mailmap example made it seem like .mailmap files are only\nuseful for commits with a wrong address for an author, when they are about\nfixing the real name. Explained this better in the text, and replaced the\nexisting example with a new one that hopefully makes things clearer.\n\nSigned-off-by: Adeodato Simó \n---\n\n Now with a Signed-off-by line. Has there even been talk of a \n commit.signoff configuration variable to always add a S-o-b line? \n This could allow to enable it on a per-project basis, which would be\n cool.\n\n Documentation/git-shortlog.txt | 31 ++++++++++++++++++++++++-------\n 1 files changed, 24 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex 7ccf31c..69e10a4 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -48,15 +48,32 @@ OPTIONS\n FILES\n -----\n \n-If the file `.mailmap` exists, it will be used for mapping author\n-email addresses to a real author name. One mapping per line, first\n-the author name followed by the email address enclosed by\n-'<' and '>'. Use hash '#' for comments. Example:\n+If a file `.mailmap` exists in the toplevel directory of the repository,\n+it will be used for mapping author email addresses to a canonical real\n+name. This can be used to coalesce together commits by the same person\n+where their name was spelled differently (whether with the same email\n+address or not).\n+\n+The format of the file is one mapping per line, first the desired author\n+name followed by the email address enclosed by '<' and '>'. Use hash '#'\n+for comments. For example, if your history contains commits by these\n+committers:\n+\n+------------\n+Author: Joe Developer \n+Author: Joe R. Developer \n+Author: Jane Doe \n+Author: Jane Doe \n+Author: Jane D. \n+------------\n+\n+Then a proper `.mailmap` file would be:\n \n ------------\n-# Keep alphabetized\n-Adam Morrow \n-Eve Jones \n+# Note how we don't need an entry for , because the\n+# real name of that author is correct already, and coalesced directly.\n+Jane Doe \n+Joe R. Developer \n ------------\n \n Author\n-- \n1.6.1\n"},{"id":"98786","messageId":"7viqp5et48.fsf@gitster.siamese.dyndns.org","threadId":"16868","inReplyTo":"1230292553-7613-1-git-send-email-dato@net.com.org.es","subject":"Re: [PATCH] git-shortlog.txt: improve documentation about .mailmap files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-12-27T11:48:39Z","receivedAt":"2008-12-27T11:48:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Adeodato Simó writes:\n\n> The previous .mailmap example made it seem like .mailmap files are only\n> useful for commits with a wrong address for an author, when they are about\n> fixing the real name. Explained this better in the text, and replaced the\n> existing example with a new one that hopefully makes things clearer.\n\nThanks.\n\n> -If the file `.mailmap` exists, it will be used for mapping author\n> -email addresses to a real author name. One mapping per line, first\n> -the author name followed by the email address enclosed by\n> -'<' and '>'. Use hash '#' for comments. Example:\n> +If a file `.mailmap` exists in the toplevel directory of the repository,\n> +it will be used for mapping author email addresses to a canonical real\n> +name. This can be used to coalesce together commits by the same person\n> +where their name was spelled differently (whether with the same email\n> +address or not).\n\nWe didn't stress \"the toplevel\" earlier, partly because it is obvious that\nthe file cannot be anything but project-tree wide (as opposed to being per\nsubdirectory, similar to .gitignore and .gitattributes). I guess it would\nnot hurt to be explicit, even though it feels slightly silly.\n\n\"..., it is used to map author email addresses to...\" would flow easier.\n\n> +The format of the file is one mapping per line, first the desired author\n> +name followed by the email address enclosed by '<' and '>'. Use hash '#'\n> +for comments.\n\nYou already introduced the term \"a canonical real name\" in the earlier\ndescription. It would be easier to read if you stick to it and say \"Each\nline consists of the canonical real name of an author, whitespaces, and an\nemail address, enclosed by '<' and '>', to map to the name\".\n\nCan a hash '#' character be anywhere on a line? E.g. how is an entry like\nthis processed?\n\n\tJane Doe # early mistake...\n\n> +... For example, if your history contains commits by these\n> +committers:\n\nI think you meant \"authors\", not \"committers\".\n\n> +------------\n> +Author: Joe Developer \n> +Author: Joe R. Developer \n> +Author: Jane Doe \n> +Author: Jane Doe \n> +Author: Jane D. \n> +------------\n\nI'd suggest dropping \"Author: \". You said you are listing people.\n\nIsn't random.com a real domain (the same goes for the-does.name)? It\nwould be preferrable to use addresses from .example (or .xz) top-level\ndomain.\n\nClarify that there are actually two people in the list above, and explain\nthat they are one Joe with two spellings who prefers to be referred to\nwith his middle initial, and one Jane with three spellings who prefers to\nshow the family name fully spelled out. Do not force your readers guess\nwhich spelling is preferred for each person in the example. It would make\nit easier for them to understand the example you will give them next and\nto agree that the mailmap is \"proper\".\n\n> +Then a proper `.mailmap` file would be:\n>\n> ------------\n> -# Keep alphabetized\n> -Adam Morrow \n> -Eve Jones \n> +# Note how we don't need an entry for , because the\n> +# real name of that author is correct already, and coalesced directly.\n> +Jane Doe \n> +Joe R. Developer \n> ------------\n"}]}