"brian m. carlson" <sandals@xxxxxxxxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxxx> 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, -- Jakub Narębski
