| Message ID | 20191102192615.10013-3-sandals@crustytoothpaste.net (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation for common user misconceptions | expand |
"brian m. carlson" <sandals@crustytoothpaste.net> writes: > It's a frequent misconception that the user.name variable controls > authentication in some way, and as a result, beginning users frequently > attempt to change it when they're having authentication troubles. > Document that the convention is that this variable represents some form > of a human's personal name, although that is not required. In addition, > address concerns about whether Unicode is supported. > > Use the term "personal name" as this is likely to draw the intended > contrast, be applicable across cultures which may have different naming > conventions, and be easily understandable to people who do not speak > English as their first language. Indicate that "some form" is > conventionally used, as people may use a nickname or preferred name > instead of a full legal name. This reminds me of "Personal names around the world" by W3C https://www.w3.org/International/questions/qa-personal-names > > Point users who may be confused about authentication to an appropriate > configuration option instead. Provide a shortened form of this > information in the configuration option description. > > Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> I like this change! Un-confusing users is always a win. > --- > Documentation/config/user.txt | 7 ++++++- > Documentation/git-commit.txt | 6 ++++++ > 2 files changed, 12 insertions(+), 1 deletion(-) > > diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt > index a1f80e823c..f0edb06329 100644 > --- a/Documentation/config/user.txt > +++ b/Documentation/config/user.txt > @@ -13,7 +13,12 @@ committer.email:: > Also, all of these can be overridden by the `GIT_AUTHOR_NAME`, > `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, > `GIT_COMMITTER_EMAIL` and `EMAIL` environment variables. > - See linkgit:git-commit[1] for more information. > ++ > +Note that the `name` forms of these variables conventionally refer to > +some form of a personal name. > +See linkgit:git-commit[1] for more information on these settings and > +the `credential.username` option if you're looking for authentication > +credentials instead. Minor nit: should this be one paragraph or two - the linebreak after "of a personal name." looks a bit strange? No need for a change: just idly wondering. > > user.useConfigOnly:: > Instruct Git to avoid trying to guess defaults for `user.email` > diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt > index f684f7fdc2..3a69d82d52 100644 > --- a/Documentation/git-commit.txt > +++ b/Documentation/git-commit.txt > @@ -467,6 +467,12 @@ if set: > > (nb "<", ">" and "\n"s are stripped) > > +The author and committer names are by convention some form of a personal name > +(that is, the name by which other humans refer to you), although Git does not > +enforce or require any particular form. Arbitrary Unicode may be used, subject > +to the constraints listed above. This name has no effect on authentication; for > +that, see the `credential.username` variable in linkgit::git-config[1]. Just ensuring that I understand it correctly: by "constraints" you mean stripping of "<", ">" and "\n" (and by implication "\0")? Should we say anything about encoding? > + > In case (some of) these environment variables are not set, the information > is taken from the configuration items user.name and user.email, or, if not > present, the environment variable EMAIL, or, if that is not set, Best,
On 2019-11-03 at 13:13:57, Jakub Narebski wrote: > This reminds me of "Personal names around the world" by W3C > https://www.w3.org/International/questions/qa-personal-names I hadn't read that document before, but it's definitely the approach I was going for. People all over the world use Git, and we should make it as usable for all of those people as we can. > Minor nit: should this be one paragraph or two - the linebreak after "of > a personal name." looks a bit strange? > > No need for a change: just idly wondering. Good question. I had explained this in my original patch but had to reformat the patch and forgot to include this. The existing text uses a line break after each sentence, and in AsciiDoc that doesn't introduce a new paragraph; only a blank line does that. I opted to keep this consistent with the rest of the description of this item. > Just ensuring that I understand it correctly: by "constraints" you mean > stripping of "<", ">" and "\n" (and by implication "\0")? Yes, that's correct. > Should we say anything about encoding? I don't think it's necessary; since we told people that arbitrary Unicode is permitted, hopefully they will determine that they should use UTF-8, or, for Windows environment variables, UTF-16. Unfortunately, there's not a good way to get UTF-8 environment variables in Windows, so "Unicode" is the best we can do there. I'm happy to gloss over the fact that they can use something else because (a) while they can, they should not and (b) if they do, they'll know that they're obviously restricted to that subset of Unicode.
diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt index a1f80e823c..f0edb06329 100644 --- a/Documentation/config/user.txt +++ b/Documentation/config/user.txt @@ -13,7 +13,12 @@ committer.email:: Also, all of these can be overridden by the `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL` and `EMAIL` environment variables. - See linkgit:git-commit[1] for more information. ++ +Note that the `name` forms of these variables conventionally refer to +some form of a personal name. +See linkgit:git-commit[1] for more information on these settings and +the `credential.username` option if you're looking for authentication +credentials instead. user.useConfigOnly:: Instruct Git to avoid trying to guess defaults for `user.email` diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index f684f7fdc2..3a69d82d52 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -467,6 +467,12 @@ if set: (nb "<", ">" and "\n"s are stripped) +The author and committer names are by convention some form of a personal name +(that is, the name by which other humans refer to you), although Git does not +enforce or require any particular form. Arbitrary Unicode may be used, subject +to the constraints listed above. This name has no effect on authentication; for +that, see the `credential.username` variable in linkgit::git-config[1]. + In case (some of) these environment variables are not set, the information is taken from the configuration items user.name and user.email, or, if not present, the environment variable EMAIL, or, if that is not set,
It's a frequent misconception that the user.name variable controls authentication in some way, and as a result, beginning users frequently attempt to change it when they're having authentication troubles. Document that the convention is that this variable represents some form of a human's personal name, although that is not required. In addition, address concerns about whether Unicode is supported. Use the term "personal name" as this is likely to draw the intended contrast, be applicable across cultures which may have different naming conventions, and be easily understandable to people who do not speak English as their first language. Indicate that "some form" is conventionally used, as people may use a nickname or preferred name instead of a full legal name. Point users who may be confused about authentication to an appropriate configuration option instead. Provide a shortened form of this information in the configuration option description. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> --- Documentation/config/user.txt | 7 ++++++- Documentation/git-commit.txt | 6 ++++++ 2 files changed, 12 insertions(+), 1 deletion(-)