[PATCH v2 1/3] doc: provide guidance on user.name format

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Oct 17, 2019, 00:53 UTC
Message-ID: <20191017005330.9021-2-sandals@crustytoothpaste.net>
In-Reply-To: <20191017005330.9021-1-sandals@crustytoothpaste.net>

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.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-commit-tree.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 4b90b9c12a..c794843634 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -92,6 +92,12 @@ if set:
 
 (nb "<", ">" and "\n"s are stripped)
 
+The author and committer names are by convention some form of a personal name,
+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,