Re: [PATCH v3 2/4] doc: provide guidance on user.name format

[Jakub Narebski <jnareb@gmail.com>]

"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,
-- 
Jakub Narębski