mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "brian m. carlson" <>
To: <>
Subject: [PATCH] doc: provide guidance on format
Date: Sat, 14 Sep 2019 21:02:19 +0000	[thread overview]
Message-ID: <> (raw)

It's a frequent misconception that the 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 <>
There are a *lot* of users on Stack Overflow who have difficulty with
what controls, such that it may be one of the top questions.
Additionally, we occasionally see issues from new contributors to Git as
well.  Furthermore, other VCS systems do things differently, so it's
best to document the conventional expectations for users explicitly.

Users may or may not read the documentation, but at least we've done our
best at providing them helpful information should they choose to do so.

 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..34a8496b0e 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,
+as opposed to a username, 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 and, or, if not
 present, the environment variable EMAIL, or, if that is not set,

             reply	other threads:[~2019-09-14 21:03 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-14 21:02 brian m. carlson [this message]
2019-09-15 22:18 ` [PATCH] doc: provide guidance on format Junio C Hamano
2019-09-15 22:57   ` brian m. carlson

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).