[v4,3/5] doc: provide guidance on user.name format
diff mbox series

Message ID 20200120173343.4102954-4-sandals@crustytoothpaste.net
State New
Headers show
Series
  • Documentation for common user misconceptions
Related show

Commit Message

brian m. carlson Jan. 20, 2020, 5:33 p.m. UTC
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(-)

Comments

Junio C Hamano Jan. 21, 2020, 10:35 p.m. UTC | #1
"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> 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 environment variables section of git(1) seems to be much more
detailed than what we have in git-commit(1) after the two previous
steps.  I do not mind keeping the reference to git-commit here, but
I think it is also OK to refer to the description in git(1) there,
too.

> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 7b61c9ba79..13f653989f 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -475,6 +475,12 @@ variables, 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].
> +

Good.

Patch
diff mbox series

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 7b61c9ba79..13f653989f 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -475,6 +475,12 @@  variables, 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,