{"thread":{"id":"51851","subject":"[PATCH] doc: provide guidance on user.name format","startedAt":"2019-09-14T21:03:06Z","lastAt":"2019-09-15T22:57:42Z","messageCount":3,"participants":["brian m. carlson","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"382376","messageId":"20190914210219.753136-1-sandals@crustytoothpaste.net","threadId":"51851","inReplyTo":null,"subject":"[PATCH] doc: provide guidance on user.name format","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-09-14T21:02:19Z","receivedAt":"2019-09-14T21:03:06Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"It's a frequent misconception that the user.name variable controls\nauthentication in some way, and as a result, beginning users frequently\nattempt to change it when they're having authentication troubles.\nDocument that the convention is that this variable represents some form\nof a human's personal name, although that is not required.  In addition,\naddress concerns about whether Unicode is supported.\n\nUse the term \"personal name\" as this is likely to draw the intended\ncontrast, be applicable across cultures which may have different naming\nconventions, and be easily understandable to people who do not speak\nEnglish as their first language.  Indicate that \"some form\" is\nconventionally used, as people may use a nickname or preferred name\ninstead of a full legal name.\n\nPoint users who may be confused about authentication to an appropriate\nconfiguration option instead.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\nThere are a *lot* of users on Stack Overflow who have difficulty with\nwhat user.name controls, such that it may be one of the top questions.\nAdditionally, we occasionally see issues from new contributors to Git as\nwell.  Furthermore, other VCS systems do things differently, so it's\nbest to document the conventional expectations for users explicitly.\n\nUsers may or may not read the documentation, but at least we've done our\nbest at providing them helpful information should they choose to do so.\n\n Documentation/git-commit-tree.txt | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\nindex 4b90b9c12a..34a8496b0e 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -92,6 +92,12 @@ if set:\n \n (nb \"<\", \">\" and \"\\n\"s are stripped)\n \n+The author and committer names are by convention some form of a personal name,\n+as opposed to a username, although Git does not enforce or require any\n+particular form. Arbitrary Unicode may be used, subject to the constraints\n+listed above. This name has no effect on authentication; for that, see the\n+`credential.username` variable in linkgit::git-config[1].\n+\n In case (some of) these environment variables are not set, the information\n is taken from the configuration items user.name and user.email, or, if not\n present, the environment variable EMAIL, or, if that is not set,\n"},{"id":"382404","messageId":"xmqqtv9db3vk.fsf@gitster-ct.c.googlers.com","threadId":"51851","inReplyTo":"20190914210219.753136-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH] doc: provide guidance on user.name format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-09-15T22:18:07Z","receivedAt":"2019-09-15T22:18:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n\n> Users may or may not read the documentation, but at least we've done our\n> best at providing them helpful information should they choose to do so.\n\nGood.\n\n>  Documentation/git-commit-tree.txt | 6 ++++++\n>  1 file changed, 6 insertions(+)\n>\n> diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\n> index 4b90b9c12a..34a8496b0e 100644\n> --- a/Documentation/git-commit-tree.txt\n> +++ b/Documentation/git-commit-tree.txt\n> @@ -92,6 +92,12 @@ if set:\n>  \n>  (nb \"<\", \">\" and \"\\n\"s are stripped)\n>  \n> +The author and committer names are by convention some form of a personal name,\n> +as opposed to a username, although Git does not enforce or require any\n> +particular form.\n\nI have a lot of trouble with 'username' in the context of this\nparagraph.\n\nAfter all, you are describing the name appropriate to be set as the\nvalue of the user.name configuration, and you are trying to stress\nthat the name used there is different from and has nothing to do\nwith the name machines use to identify the user.  In the paragraph\nthat follows this new paragraph, there is a reference to \"system\nuser name\", which is still not great but probably better than\n\"username\" above.  Perhaps there is a term that is distinct enough\nfrom \"user name\" that is commonly used I am forgetting?  I am almost\ntempted to say \"user id\", but there must be even better phrases.  I\ndunno.\n\n> Arbitrary Unicode may be used, subject to the constraints\n> +listed above. This name has no effect on authentication; for that, see the\n> +`credential.username` variable in linkgit::git-config[1].\n> +\n>  In case (some of) these environment variables are not set, the information\n>  is taken from the configuration items user.name and user.email, or, if not\n>  present, the environment variable EMAIL, or, if that is not set,\n\nThanks.\n\n"},{"id":"382406","messageId":"20190915225733.GX11334@genre.crustytoothpaste.net","threadId":"51851","inReplyTo":"xmqqtv9db3vk.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] doc: provide guidance on user.name format","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-09-15T22:57:34Z","receivedAt":"2019-09-15T22:57:42Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2019-09-15 at 22:18:07, Junio C Hamano wrote:\n> \"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n> > diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\n> > index 4b90b9c12a..34a8496b0e 100644\n> > --- a/Documentation/git-commit-tree.txt\n> > +++ b/Documentation/git-commit-tree.txt\n> > @@ -92,6 +92,12 @@ if set:\n> >  \n> >  (nb \"<\", \">\" and \"\\n\"s are stripped)\n> >  \n> > +The author and committer names are by convention some form of a personal name,\n> > +as opposed to a username, although Git does not enforce or require any\n> > +particular form.\n> \n> I have a lot of trouble with 'username' in the context of this\n> paragraph.\n> \n> After all, you are describing the name appropriate to be set as the\n> value of the user.name configuration, and you are trying to stress\n> that the name used there is different from and has nothing to do\n> with the name machines use to identify the user.  In the paragraph\n> that follows this new paragraph, there is a reference to \"system\n> user name\", which is still not great but probably better than\n> \"username\" above.  Perhaps there is a term that is distinct enough\n> from \"user name\" that is commonly used I am forgetting?  I am almost\n> tempted to say \"user id\", but there must be even better phrases.  I\n> dunno.\n\nI wonder if we should just omit that aside, then, since I'm not sure of\na less ambiguous term for \"how I identify myself to a computer\".  I think\ndescribing the convention as \"some form of a personal name\" is probably\nsufficient to tell people what we suggest they do.\n\nMy first draft of that sentence didn't include the part within the\ncommas at all.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"}]}