{"thread":{"id":"16886","subject":"[PATCH v2] git-shortlog.txt: improve documentation about .mailmap files","startedAt":"2008-12-27T18:21:40Z","lastAt":"2008-12-27T18:23:30Z","messageCount":2,"participants":["Adeodato Simó"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"98801","messageId":"20081227182140.GA28946@chistera.yi.org","threadId":"16886","inReplyTo":"7viqp5et48.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] git-shortlog.txt: improve documentation about .mailmap files","fromName":"Adeodato Simó","fromEmail":"dato@net.com.org.es","sentAt":"2008-12-27T18:21:40Z","receivedAt":"2008-12-27T18:21:40Z","isPatch":true,"sender":{"key":"dato@net.com.org.es","avatar":"https://gravatar.com/avatar/952ec7d5d5663eb8baf631b5c37f9c58480a881920dd5f8a2d3a71f969b72b53?d=mp&s=160"},"body":"* Junio C Hamano [Sat, 27 Dec 2008 03:48:39 -0800]:\n\n> 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\n> Thanks.\n\nThanks for your review!\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> We didn't stress \"the toplevel\" earlier, partly because it is obvious that\n> the file cannot be anything but project-tree wide (as opposed to being per\n> subdirectory, similar to .gitignore and .gitattributes). I guess it would\n> not hurt to be explicit, even though it feels slightly silly.\n\nHm. I'd prefer to keep it in if you don't mind much.\n\n> \"..., it is used to map author email addresses to...\" would flow easier.\n\nChanged.\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\n> You already introduced the term \"a canonical real name\" in the earlier\n> description. It would be easier to read if you stick to it and say \"Each\n> line consists of the canonical real name of an author, whitespaces, and an\n> email address, enclosed by '<' and '>', to map to the name\".\n\nChanged.\n\n> Can a hash '#' character be anywhere on a line? E.g. how is an entry like\n> this processed?\n\n> \tJane Doe # early mistake...\n\nIt is processed correctly. Good suggestion to have it documented. I did:\n\n Use hash '#' for comments, either on their own line, or after the\n email address.\n\n> > +... For example, if your history contains commits by these\n> > +committers:\n\n> I think you meant \"authors\", not \"committers\".\n\nOk.\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> I'd suggest dropping \"Author: \". You said you are listing people.\n\nAnd ok.\n\n> Isn't random.com a real domain (the same goes for the-does.name)? It\n> would be preferrable to use addresses from .example (or .xz) top-level\n> domain.\n\nI wanted to use a real TLD to clearly convey that these were for real\naddresses and not misconfigured ones. How about \"example.com\"? (This is\nused in other Documentation files.)\n\n> Clarify that there are actually two people in the list above, and explain\n> that they are one Joe with two spellings who prefers to be referred to\n> with his middle initial, and one Jane with three spellings who prefers to\n> show the family name fully spelled out. Do not force your readers guess\n> which spelling is preferred for each person in the example. It would make\n> it easier for them to understand the example you will give them next and\n> to agree that the mailmap is \"proper\".\n\nGood point. As always, what it's obvious to the writer may not be to the\nreader. Thanks.\n\nI also added a sentence mentioning that names can appear more than once,\nbut addresses can't.\n\nCan you take another look? (Amended patch coming.)\n\n-- \nAdeodato Simó dato at net.com.org.es\nDebian Developer adeodato at debian.org\n \n- You look beaten.\n- I just caught Tara laughing with another man.\n- Are you sure they weren't just... kissing or something?\n- No, they were laughing.\n -- Denny Crane and Alan Shore\n"},{"id":"98800","messageId":"1230402210-30565-1-git-send-email-dato@net.com.org.es","threadId":"16886","inReplyTo":"20081227182140.GA28946@chistera.yi.org","subject":"[PATCH v2] git-shortlog.txt: improve documentation about .mailmap files","fromName":"Adeodato Simó","fromEmail":"dato@net.com.org.es","sentAt":"2008-12-27T18:23:30Z","receivedAt":"2008-12-27T18:23:30Z","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 Documentation/git-shortlog.txt | 40 +++++++++++++++++++++++++++++++++-------\n 1 files changed, 33 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex 7ccf31c..4a76b7f 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -48,15 +48,41 @@ 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 is used to map author email addresses to a canonical real name. This\n+can be used to coalesce together commits by the same person where their\n+name was spelled differently (whether with the same email address or\n+not).\n+\n+Each line in the file consists, in this order, of the canonical real name\n+of an author, whitespace, and an email address (enclosed by '<' and '>')\n+to map to the name. Use hash '#' for comments, either on their own line,\n+or after the email address.\n+\n+A canonical name may appear in more than one line, associated with\n+different email addresses, but it doesn't make sense for a given address\n+to appear more than once (if that happens, the latest line in which it\n+appears will take effect).\n+\n+So, for example, if your history contains commits by two authors, Jane\n+and Joe, whose names appear in the repository under several forms:\n+\n+------------\n+Joe Developer \n+Joe R. Developer \n+Jane Doe \n+Jane Doe \n+Jane D. \n+------------\n+\n+Then, supposing Joe wants his middle name initial used, and Jane prefers\n+her family name fully spelled out, 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.307.g07803\n"}]}